Dated source reference. Current release status: handoff state. Full original relative paths are in the developer archive.

Event and round captions from external applications

An external dynasty/career/client app can pass optional event and round context through the existing version1 match request's identity.metadata. This is match data, independent of the roster and native tournament database. The broker already preserves generic metadata in the bound match and immutable results.

Add this fragment to a complete match request:

{
  "identity": {
    "metadata": {
      "org.openhoops.presentation": {
        "format": "openhoops.match_presentation",
        "version": 1,
        "event": {"id": "maui-invitational", "name": "Maui Invitational"},
        "round": {"id": "championship", "name": "Championship"}
      }
    }
  }
}

This fragment omits the other required request/identity fields. Keep the existing explicit match/team/player/ruleset identities. Clients binding through POST /v1/matches directly put the same namespaced value in the binding body's metadata object.

The default caption is Maui Invitational - Championship. Other examples produce NCAA Tournament - Sweet 16 and American Conference Tournament - Semifinal. Names are free text; there is no fixed tournament or round enum and no first-party league dependency. A round can be Round Robin Game 3, Regional Final or another app-defined label.

When no display override is supplied, full names form the complete caption and short names form the compact caption. A supplied display_label also becomes the compact fallback, unless scorebug_label is supplied. Explicit null for either label hides that binding; null for the full label also hides its compact fallback unless a compact override is provided. Omitted context produces no event caption. Missing, explicit null and IDs remain distinct in copied data/context identity.

All fields are optional within the versioned context. If an event/round object is supplied it needs a name. Whitespace-only/padded labels, invalid Unicode and control characters refuse in the helper. UTF-8 byte limits: event name128/short64, round name96/short48, full label255, compact override128, subtitle255. Optional IDs use1–96 identifier characters. The existing total match-metadata8KiB limit still applies, including other app metadata.

Producer and consumer helpers

match_context.py is independent of the game/API implementation:

from match_context import NAMESPACE, validated_metadata, from_match

identity_plan["metadata"] = validated_metadata({
    **identity_plan.get("metadata", {}),
    NAMESPACE: {
        "format": "openhoops.match_presentation",
        "version": 1,
        "event": {"name": "NCAA Tournament"},
        "round": {"name": "Sweet 16"},
        "scorebug_label": "NCAA Tournament - Sweet 16"
    }
})
# Launch/bind through the existing public API. Later, read the bound match:
view = from_match(bound_match, expected_match_id, expected_run_id)

Put presentation/authoring on the application's import path for this source helper. The JSON Schema documents the versioned namespace; the helper additionally enforces byte/Unicode/trim constraints. The existing broker transports generic finite metadata and does not enforce this presentation namespace's schema. Producers should validate before submitting; consumers must validate before drawing. No new HTTP endpoint/API version/native rule callback or roster-editor field is introduced.

Read the match context once for the bound match, checking match/run identity, and keep it alongside live copied score/clock data. The current snapshot does not gain a new event/round field. No per-frame HTTP request is required. The returned context sha256 includes presence, version, labels and IDs; it is separate from the roster/companion context hash.

Presentation bindings

The draft core now exposes match_event_name, match_round_name, match_event_label, match_event_short_label and match_event_subtitle. from_match returns validated bounded binding values and their missing/null reasons. A future live adapter must copy them to State.values and the independent State.presentation_sha256; changing that identity clears old layer visibility. This prevents an old round caption from carrying across a context switch.

The ESPN CBB development scaffold has an optional event/round text node. Ordinary games leave it hidden. This is binding/command composition support; actual font styling, text fitting and drawing inside the game still await ESPN resources and native/GPU integration. Supplying an event name does not create a bracket, schedule a tournament, select rules or certify any NCAA behavior.

Work68 source presentation68b passes17 Windows authoring/context/HTTP tests, schema validation, MSVC x86 warnings-as-errors and112 composition checks. Actual HTTP tests use the production API with simulated game input; they verify namespaced metadata through binding, results, independent ACKs and persisted reopen. No game/desktop/native installation is involved. Closeout and exact checks.