Add Schema as a top-level concept (beta)

[Fannon]

Summary

Introduces Schema as a new, lightweight top-level ORD concept (beta).

A Schema describes the concrete structure of a data object: a DTO, an event payload, an API request/response model, or the contract of a whole document / declarative-config object (e.g. a Kubernetes CRD — ORD's own published JSON Schema for ORD Documents is such an example).

This is deliberately distinct from EntityType:

	EntityType	Schema
Represents	conceptual domain model / business term (a "noun")	concrete serialization structure ("how it is shaped on the wire")
Answers	what it means	how it is shaped

The same EntityType can have several Schemas as physical representations, depending on API/protocol/format. A Schema references the EntityType(s) it represents (direction: Schema → EntityType) via relatedEntityTypes as {ordId, relationType} objects (ord:represents / ord:partial-representation, extensible).

Design decisions

• Modeled on Capability (lean). Required: ordId, title, version, releaseStatus, visibility. partOfPackage is optional (lighter than Capability).
• Optional compatibility mode (none/backward/forward/full), mirroring schema-registry semantics (Confluent, AWS Glue, CNCF xRegistry).
• SchemaDefinition mirrors CapabilityDefinition (type/mediaType/url/accessStrategies/visibility/purpose). type is an extensible enum: global industry-standard formats are bare consts (json-schema-v7, json-schema-v2020-12, avro-v1, protobuf-v3, xsd-v1, sap-csn-interop-effective-v1), consistent with existing openapi-v3/asyncapi-v2; anything else uses a namespace-prefixed Specification ID or custom.
• relatedSchemas (not exposedSchemas) — resolved design decision. The first draft used an exposedSchemas object on API/Event (mirroring exposedEntityTypes). We chose instead a single, uniform relatedSchemas field on ApiResource, EventResource, and Capability, modeled as a RelatedSchema object {ordId, relationType}. Rationale:
  • Uniformity — one field name and shape across all three resources, rather than exposedSchemas on some and relatedSchemas on others.
  • Flexibility — covers exposes/contains and looser associations without baking containment into the field name.
  • Protocol/representation nuance lives in relationType (extensible Concept ID), matching how the same EntityType can have different schemas per API/protocol. Seeded values: ord:exposes (schema contained in an API contract) and ord:payload (event payload schema).

Relationships

• API/Event/Capability → Schema: relatedSchemas (RelatedSchema = {ordId, relationType}). An API contract typically relates many schemas (ord:exposes); an event references its payload schema (ord:payload).
• Schema → EntityType: relatedSchemas' counterpart on the Schema side is relatedEntityTypes (SchemaEntityTypeRelation), pointing to the concept it represents.

Changes

• New definitions: Schema, SchemaDefinition, SchemaEntityTypeRelation, RelatedSchema.
• schemas[] array on the Document root (beta); added to x-property-order.
• relatedSchemas on ApiResource, EventResource, and Capability (beta).
• Added "1.17" to the openResourceDiscovery version enum.
• New concept doc page (docs/spec-v1/concepts/schema.md), a validating example (examples/documents/document-schemas.json), and a CHANGELOG entry.
• Regenerated types/interfaces/UMS metadata.

Introduced as beta so the enum values and relationships can iterate before locking.

Open questions / for discussion

1. Naming: Schema vs DataSchema (potential confusion with "JSON Schema").
2. Should compatibility include transitive variants (backward-transitive, etc.)?
3. Schema-to-Schema composition references (Confluent-style) — needed now, or defer?
4. SchemaDefinition.type seed set — which formats do we standardize now? Do we keep protobuf-v3, and what else belongs in the initial list? The big three across every major registry (Confluent, AWS Glue, Apicurio) are Avro, JSON Schema, and Protobuf — Protobuf is a first-class citizen everywhere, so protobuf-v3 looks warranted. Apicurio additionally handles OpenAPI, AsyncAPI, GraphQL, WSDL, and XSD. Since type is an extensible enum (anything can be added later via a namespaced Specification ID or custom), the question is which to seed as standardized bare consts vs leave to extension. Current seed: json-schema-v7, json-schema-v2020-12, avro-v1, protobuf-v3, xsd-v1, sap-csn-interop-effective-v1. Candidates to consider: newer JSON Schema drafts, graphql-sdl (already exists for API definitions). Also: is per-version granularity (protobuf-v3 vs a single protobuf) the right approach?
5. Exact seed set of relationType values (ord:exposes, ord:payload, ord:represents, ord:partial-representation).
6. Guidance on Schema vs EntityType definitions (beta) so the same schema isn't described in both places.

Verification

npm run lint, npm run test (16/16), and npm run build all pass. No broken links originate from the new pages.

🤖 Generated with Claude Code

[open-resource-discovery-bot]

PR Preview
🚀 View preview at: https://open-resource-discovery.github.io/pr-preview/specification/pr-163/
Built to branch main at 2026-07-31 07:22 UTC.
open-resource-discovery/pr-preview-action