OpenProposal 3.0 JSON Schema Unofficial

Decision records · Changes we propose

D-041 What does a field hold whose values are terms that the specification doesn't list?

Proposal Decision 43 on the supporting page of #121. Cited on main and with the open PRs.

What we propose

Each field gets a named open vocabulary with the core terms the specification lists, none yet, so each accepts namespaced terms <domain>:<term> only.

As written

Each field whose values are terms the text doesn't list takes a bare term, such as modeled, vast_4_2, mrc, or s3: an audience's provenance, creative_delivery.protocol, an asset's approval_status, availability's unit and basis, committed_metrics[]'s basis, reporting's delivery_mechanism, and, on main, an external reference's role.

The as-written variant takes the option bare-term. Switch the type map to As written to see it.

Options

  • named-open-vocabulary Chosen

    Each field gets a named open vocabulary with the core terms the specification lists, none yet, so each accepts namespaced terms <domain>:<term> only.

  • bare-term As written

    Each field takes any bare term, letters and digits joined by underscores, as the examples write them.

Why

Each of these fields holds terms: an audience's provenance, a creative delivery's protocol, an asset's approval_status, an availability's unit and basis, a guarantee's basis, a report's delivery_mechanism, and, on main, an external reference's role. The text lists no terms for them, and the examples write bare terms such as modeled, javascript_tag, mrc, seller_reported, vast_4_2, api, and s3. Every open vocabulary of the specification is a core list that implementations extend with namespaced terms. A bare term is open in the wrong direction: it accepts any word as if it were core and rejects the namespaced extension. A named vocabulary per field gives each concept a type, and its core grows as the specification lists terms. The schema departs from the examples: until the specification lists a field's core terms, the field accepts only namespaced terms.

What we ask the specification to change

List the core terms of each field whose values are terms. These are an audience's provenance, creative_delivery.protocol, an asset's approval_status, availability's unit and basis, committed_metrics[]'s basis, and reporting's delivery_mechanism. The examples use modeled, first_party, javascript_tag, vast_4_2, mrc, seller_reported, api, and s3, which aren't listed. Until they are, each field accepts only namespaced extension terms.

The specification lines it rests on

Each line is quoted as the record pins it. Expand an item to read the quote.

main

  • § 5.3, the audiences row's description: the inline object L233 at 44dfaaf
    { id, name, taxonomy_ref, provenance, addressable_scale }
  • § 5.4, the creative_delivery row's description: the inline object L245 at 44dfaaf
    { method: buyer_hosted | seller_hosted | api | platform_managed, protocol, secure_required, endpoint }
  • § 5.4, the assets[] row's description: the inline object L246 at 44dfaaf
    { asset_id, format_ref, url_or_tag, submitted_at, approval_status }
  • § 5.6, the availability row's description: the inline object L275 at 44dfaaf
    { unit, basis, as_of, granularity, type: forecast | reservable, quantity }
  • § 5.7, the committed_metrics[] row's description: the inline object L320 at 44dfaaf
    { metric, value, basis }
  • § 5.7, the reporting row's description: the inline object L323 at 44dfaaf
    { feed_type: log_level | aggregate | none, cadence, delivery_mechanism, metrics_provided[], latency }
  • § 5.10, the external_references[] row L349 at 44dfaaf
    external_references[] | Array[Object] | derived | { system, namespace, id, role }. Replaces platform-specific key names. A buyer-owned reference such as a Prisma io_id is supplied

With the open PRs

  • § 5.3, the audiences row's description: the inline object L226 on main at 981a74e
    { id, name, taxonomy_ref, provenance, addressable_scale }
  • § 5.4, the creative_delivery row's description: the inline object L238 on main at 981a74e
    { method: buyer_hosted | seller_hosted | api | platform_managed, protocol, secure_required, endpoint }
  • § 5.4, the assets[] row's description: the inline object L239 on main at 981a74e
    { asset_id, format_ref, url_or_tag, submitted_at, approval_status }
  • § 5.6, the availability row's description: the inline object L268 on main at 981a74e
    { unit, basis, as_of, granularity, type: forecast | reservable, quantity }
  • § 5.7, the committed_metrics[] row's description: the inline object L313 on main at 981a74e
    { metric, value, basis }
  • § 5.7, the reporting row's description: the inline object L316 on main at 981a74e
    { feed_type: log_level | aggregate | none, cadence, delivery_mechanism, metrics_provided[], latency }
  • § 5.10, the external_references[] row L352 in #75
    external_references[] | Array[Object] | derived | { system, namespace, id, role }. Replaces platform-specific key names. A buyer-owned reference such as a Prisma io_id is supplied. Documented role values: io, an IO id generated by an order management system and carried back on the line item; agreement, a buyer-held agreement id

Examples that follow the text, not this change

ExampleWhereWhyInput
examples/line-item-audio.yaml/committed_metrics/0/basisThe example follows the text, which lists no terms for basis: it writes seller_reported. We propose namespaced terms in a field until the specification lists its core terms, seller_reported among them.main, open PRs
examples/line-item-ctv-bonus.yaml/creative_delivery/protocolThe example follows the text, which lists no terms for protocol: it writes vast_4_2. We propose namespaced terms in a field until the specification lists its core terms, vast_4_2 among them.open PRs
examples/line-item-ctv.yaml/committed_metrics/0/basisThe example follows the text, which lists no terms for basis: it writes seller_reported. We propose namespaced terms in a field until the specification lists its core terms, seller_reported among them.main, open PRs
examples/line-item-ctv.yaml/creative_delivery/protocolThe example follows the text, which lists no terms for protocol: it writes vast_4_2. We propose namespaced terms in a field until the specification lists its core terms, vast_4_2 among them.main, open PRs
examples/line-item-display.yaml/audiences/available/1The example follows the text, which states no form for an option's id and lists no terms for provenance: it writes the readable name ep:hnw-investors and the term modeled. We propose a UUID for every ID a party mints, a catalog entry's id included. We also propose namespaced terms in a field until the specification lists its core terms.main, open PRs
examples/line-item-display.yaml/audiences/available/2The example follows the text, which states no form for an option's id and lists no terms for provenance: it writes the readable name ep:cfo-finance-leaders and the term first_party. We propose a UUID for every ID a party mints, a catalog entry's id included. We also propose namespaced terms in a field until the specification lists its core terms.main, open PRs
examples/line-item-display.yaml/committed_metrics/0/basisThe example follows the text, which lists no terms for basis: it writes mrc. We propose namespaced terms in a field until the specification lists its core terms, mrc among them.main, open PRs
examples/line-item-display.yaml/creative_delivery/protocolThe example follows the text, which lists no terms for protocol: it writes javascript_tag. We propose namespaced terms in a field until the specification lists its core terms, javascript_tag among them.main, open PRs
examples/line-item-display.yaml/reporting/available/0/delivery_mechanismThe example follows the text, which lists no terms for delivery_mechanism: it writes api. We propose namespaced terms in a field until the specification lists its core terms, api among them.main, open PRs
examples/line-item-display.yaml/reporting/available/1/delivery_mechanismThe example follows the text, which lists no terms for delivery_mechanism: it writes s3. We propose namespaced terms in a field until the specification lists its core terms, s3 among them.main, open PRs
examples/line-item-rewarded-video.yaml/committed_metrics/0/basis
/committed_metrics/1/basis		The example follows the text, which lists no terms for basis: it writes mrc. We propose namespaced terms in a field until the specification lists its core terms, mrc among them.open PRs
examples/line-item-rewarded-video.yaml/creative_delivery/protocolThe example follows the text, which lists no terms for protocol: it writes vast_4_2. We propose namespaced terms in a field until the specification lists its core terms, vast_4_2 among them.open PRs

What it shapes

main: AssetApprovalStatus, AvailabilityBasis, AvailabilityUnit, CreativeDeliveryProtocol, ExternalReferenceRole, MeasurementBasis, Provenance, ReportingDeliveryMechanism, AssetsEntry.approval_status, AssetsEntry.asset_id, AssetsEntry.format_ref, AssetsEntry.submitted_at, AssetsEntry.url_or_tag, AudiencesOption.addressable_scale, AudiencesOption.id, AudiencesOption.name, AudiencesOption.provenance, AudiencesOption.taxonomy_ref, Availability.as_of, Availability.basis, Availability.granularity, Availability.quantity, Availability.type, Availability.unit, CommittedMetricsEntry.basis, CommittedMetricsEntry.metric, CommittedMetricsEntry.value, CreativeDelivery.endpoint, CreativeDelivery.method, CreativeDelivery.protocol, CreativeDelivery.secure_required, LineItem.external_references, ReportingOption.cadence, ReportingOption.delivery_mechanism, ReportingOption.feed_type, ReportingOption.latency, ReportingOption.metrics_provided

With the open PRs: AssetApprovalStatus, AvailabilityBasis, AvailabilityUnit, CreativeDeliveryProtocol, MeasurementBasis, Provenance, ReportingDeliveryMechanism, AssetsEntry.approval_status, AssetsEntry.asset_id, AssetsEntry.format_ref, AssetsEntry.submitted_at, AssetsEntry.url_or_tag, AudiencesOption.addressable_scale, AudiencesOption.id, AudiencesOption.name, AudiencesOption.provenance, AudiencesOption.taxonomy_ref, Availability.as_of, Availability.basis, Availability.granularity, Availability.quantity, Availability.type, Availability.unit, CommittedMetricsEntry.basis, CommittedMetricsEntry.metric, CommittedMetricsEntry.value, CreativeDelivery.endpoint, CreativeDelivery.method, CreativeDelivery.protocol, CreativeDelivery.secure_required, LineItem.external_references, ReportingOption.cadence, ReportingOption.delivery_mechanism, ReportingOption.feed_type, ReportingOption.latency, ReportingOption.metrics_provided

The record's YAML file