xregistry/spec

Purpose and Entry Points

This is a specification repository for xRegistry, an extensible REST registry model for metadata resources. It contains normative Markdown specifications and machine-readable models, not a deployable server. Start with core/primer.md, then the core API/model in core/spec.md; README.md indexes releases and related implementations maintained in separate repositories.

Core Registry Contract

The core defines registry resource management and discovery semantics, including the abstract model and REST interface. Its normative and machine-readable boundary is represented by:

• core/spec.md

• core/model.md

• core/model.schema.json

core/model.json and sample documents support model validation and consumer implementation.

Domain-Specific Extensions

Three domain registries extend the core contract rather than replacing it:

• Endpoint registry: endpoint/spec.md, endpoint/model.json, endpoint/schemas/openapi.json

• Message-definition registry: message/spec.md, message/model.json, message/schemas/openapi.json

• Schema registry: schema/spec.md, schema/model.json, schema/schemas/openapi.json

Each domain publishes equivalent document encodings as JSON Schema, Avro, and OpenAPI, creating an interoperability boundary for registry implementations and generated clients.

Supporting Specification Modules

Cross-cutting and adjacent specification work is separated from the core:

• Pagination behavior: pagination/spec.md

• CloudEvents-oriented registry profile/model: cloudevents/spec.md, cloudevents/model.json

• Discovery/early design proposals: todos/discovery.yaml, todos/primer.md

The pagination specification is a reusable REST behavior layer; CloudEvents provides a domain integration/profile built on the broader xRegistry approach.

Examples and Interoperability Fixtures

Examples act as concrete registry documents and scenario fixtures for implementers:

• Core examples: core/samples/contoso-crm.cereg, core/sample-model-full.json

• CloudEvents scenarios: cloudevents/samples/scenarios/

• Schema-oriented samples: cloudevents/samples/schemas/schemastore_org.xreg.json

These flows run from authored example/model documents through validation tooling, rather than through an application runtime.

Validation and Artifact Generation

The repository’s executable architecture is its verification pipeline. Python and Go tools validate models, schemas, links, formatting, spelling, and generated OpenAPI-related artifacts:

• tools/verify.py

• tools/verify.go

• tools/validate-models.py

• tools/schema-generator.py

Dependencies are declared in tools/requirements.txt; tools/Makefile is the local orchestration entry point. CI executes repository verification through .github/workflows/verify.yaml.

Infrastructure and External Boundaries

GitHub Actions provides automated verification, release-note handling, site regeneration, and FOSSA scanning under .github/workflows/. Published/consumed external systems are REST registry implementations and tools, explicitly hosted outside this repository (server, CLI/codegen, viewer, and registry proxies). CNCF/CloudEvents governance and release processes are documented under docs/ and are organizational rather than runtime infrastructure.