# xregistry/spec architecture

> Architecture diagram of the GitHub repository xregistry/spec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xregistry/spec
- Repository: https://github.com/xregistry/spec

## Overview

#### 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.

Main entry points: [`core/spec.md`](https://github.com/xregistry/spec/blob/main/core/spec.md) (Core REST contract), [`endpoint/schemas/openapi.json`](https://github.com/xregistry/spec/blob/main/endpoint/schemas/openapi.json) (Domain API encodings), [`core/model.schema.json`](https://github.com/xregistry/spec/blob/main/core/model.schema.json) (Core JSON Schema), [`tools/Makefile`](https://github.com/xregistry/spec/blob/main/tools/Makefile) (Local verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core Contract"]
  node_core_primer["Core primer<br/>specification<br/>[primer.md]"]
  node_core_spec["Core REST contract<br/>specification<br/>[spec.md]"]
  node_core_model["Core abstract model<br/>model specification<br/>[model.md]"]
  node_core_schema["Core JSON Schema<br/>[model.schema.json]"]
  node_core_model_json["Core model document<br/>[model.json]"]
end

subgraph group_extensions["Registry Extensions"]
  node_endpoint["Endpoint registry<br/>domain extension<br/>[spec.md]"]
  node_message["Message registry<br/>domain extension<br/>[spec.md]"]
  node_schema_registry["Schema registry<br/>domain extension<br/>[spec.md]"]
  node_domain_encodings["Domain API encodings<br/>OpenAPI and model artifacts<br/>[openapi.json]"]
  node_pagination["Pagination behavior<br/>REST module<br/>[spec.md]"]
end

subgraph group_fixtures["Examples &amp; Profiles"]
  node_cloudevents["CloudEvents profile<br/>registry profile<br/>[spec.md]"]
  node_examples["Registry examples<br/>validation fixtures<br/>[contoso-crm.cereg]"]
  node_schema_sample["Schema sample<br/>validation fixture"]
  node_proposals["Discovery proposals<br/>early design<br/>[discovery.yaml]"]
end

subgraph group_verification["Verification Pipeline"]
  node_orchestration["Local verification<br/>Make orchestration"]
  node_validators["Validation tools<br/>Python and Go tools<br/>[verify.py]"]
  node_generator["Schema generator<br/>artifact generator"]
  node_dependencies["Tool dependencies<br/>Python dependencies<br/>[requirements.txt]"]
  node_ci["GitHub Actions verification<br/>CI workflow<br/>[verify.yaml]"]
end

node_readme["Repository index<br/>documentation<br/>[README.md]"]
node_external{{"External implementations<br/>external ecosystem"}}

node_readme -->|"directs readers to"| node_core_primer
node_core_primer -->|"introduces"| node_core_spec
node_core_spec -->|"defines"| node_core_model
node_core_model -->|"machine-readable as"| node_core_schema
node_core_schema -->|"validates"| node_core_model_json
node_core_spec -->|"extended by"| node_endpoint
node_core_spec -->|"extended by"| node_message
node_core_spec -->|"extended by"| node_schema_registry
node_endpoint -->|"publishes"| node_domain_encodings
node_message -->|"publishes"| node_domain_encodings
node_schema_registry -->|"publishes"| node_domain_encodings
node_pagination -->|"augments REST behavior"| node_core_spec
node_cloudevents -->|"profiles"| node_core_spec
node_examples -->|"validated against"| node_core_schema
node_schema_sample -->|"scenario for"| node_cloudevents
node_orchestration -->|"runs"| node_validators
node_orchestration -->|"runs"| node_generator
node_dependencies -->|"supports"| node_validators
node_generator -->|"generates or verifies"| node_domain_encodings
node_validators -->|"checks"| node_core_schema
node_ci -->|"executes"| node_orchestration
node_domain_encodings -.->|"consumed by"| node_external
node_core_spec -.->|"implemented by"| node_external

click node_readme "https://github.com/xregistry/spec/blob/main/README.md"
click node_core_primer "https://github.com/xregistry/spec/blob/main/core/primer.md"
click node_core_spec "https://github.com/xregistry/spec/blob/main/core/spec.md"
click node_core_model "https://github.com/xregistry/spec/blob/main/core/model.md"
click node_core_schema "https://github.com/xregistry/spec/blob/main/core/model.schema.json"
click node_core_model_json "https://github.com/xregistry/spec/blob/main/core/model.json"
click node_endpoint "https://github.com/xregistry/spec/blob/main/endpoint/spec.md"
click node_message "https://github.com/xregistry/spec/blob/main/message/spec.md"
click node_schema_registry "https://github.com/xregistry/spec/blob/main/schema/spec.md"
click node_domain_encodings "https://github.com/xregistry/spec/blob/main/endpoint/schemas/openapi.json"
click node_pagination "https://github.com/xregistry/spec/blob/main/pagination/spec.md"
click node_cloudevents "https://github.com/xregistry/spec/blob/main/cloudevents/spec.md"
click node_examples "https://github.com/xregistry/spec/blob/main/core/samples/contoso-crm.cereg"
click node_schema_sample "https://github.com/xregistry/spec/blob/main/cloudevents/samples/schemas/schemastore_org.xreg.json"
click node_proposals "https://github.com/xregistry/spec/blob/main/todos/discovery.yaml"
click node_orchestration "https://github.com/xregistry/spec/blob/main/tools/Makefile"
click node_validators "https://github.com/xregistry/spec/blob/main/tools/verify.py"
click node_generator "https://github.com/xregistry/spec/blob/main/tools/schema-generator.py"
click node_dependencies "https://github.com/xregistry/spec/blob/main/tools/requirements.txt"
click node_ci "https://github.com/xregistry/spec/blob/main/.github/workflows/verify.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_primer,node_core_spec,node_core_model,node_core_schema,node_core_model_json toneBlue
class node_endpoint,node_message,node_schema_registry,node_domain_encodings,node_pagination toneAmber
class node_cloudevents,node_examples,node_schema_sample,node_proposals toneMint
class node_orchestration,node_validators,node_generator,node_dependencies,node_ci toneRose
class node_readme,node_external toneNeutral
```

## Components

### Core Contract

- [Core primer](https://github.com/xregistry/spec/blob/main/core/primer.md): specification · Recommended entry point for the registry model. · `core/primer.md`
- [Core REST contract](https://github.com/xregistry/spec/blob/main/core/spec.md): specification · Normative resource management and discovery semantics. · `core/spec.md`
- [Core abstract model](https://github.com/xregistry/spec/blob/main/core/model.md): model specification · `core/model.md`
- [Core JSON Schema](https://github.com/xregistry/spec/blob/main/core/model.schema.json): JSON Schema · Machine-readable core model boundary. · `core/model.schema.json`
- [Core model document](https://github.com/xregistry/spec/blob/main/core/model.json): model document · `core/model.json`

### Registry Extensions

- [Endpoint registry](https://github.com/xregistry/spec/blob/main/endpoint/spec.md): domain extension · `endpoint/spec.md`
- [Message registry](https://github.com/xregistry/spec/blob/main/message/spec.md): domain extension · `message/spec.md`
- [Schema registry](https://github.com/xregistry/spec/blob/main/schema/spec.md): domain extension · `schema/spec.md`
- [Domain API encodings](https://github.com/xregistry/spec/blob/main/endpoint/schemas/openapi.json): OpenAPI and model artifacts · Interoperability documents for implementations and generated clients. · `endpoint/schemas/openapi.json`
- [Pagination behavior](https://github.com/xregistry/spec/blob/main/pagination/spec.md): REST module · Reusable REST pagination layer. · `pagination/spec.md`

### Examples & Profiles

- [CloudEvents profile](https://github.com/xregistry/spec/blob/main/cloudevents/spec.md): registry profile · CloudEvents-oriented registry model and integration. · `cloudevents/spec.md`
- [Registry examples](https://github.com/xregistry/spec/blob/main/core/samples/contoso-crm.cereg): validation fixtures · Concrete documents and scenarios for implementers. · `core/samples/contoso-crm.cereg`
- [Schema sample](https://github.com/xregistry/spec/blob/main/cloudevents/samples/schemas/schemastore_org.xreg.json): validation fixture · `cloudevents/samples/schemas/schemastore_org.xreg.json`
- [Discovery proposals](https://github.com/xregistry/spec/blob/main/todos/discovery.yaml): early design · `todos/discovery.yaml`

### Verification Pipeline

- [Local verification](https://github.com/xregistry/spec/blob/main/tools/Makefile): Make orchestration · Local entry point for repository checks. · `tools/Makefile`
- [Validation tools](https://github.com/xregistry/spec/blob/main/tools/verify.py): Python and Go tools · Validate models, schemas, links, formatting, spelling, and generated artifacts. · `tools/verify.py`
- [Schema generator](https://github.com/xregistry/spec/blob/main/tools/schema-generator.py): artifact generator · Generates OpenAPI-related artifacts. · `tools/schema-generator.py`
- [Tool dependencies](https://github.com/xregistry/spec/blob/main/tools/requirements.txt): Python dependencies · `tools/requirements.txt`
- [GitHub Actions verification](https://github.com/xregistry/spec/blob/main/.github/workflows/verify.yaml): CI workflow · Automated repository verification and publication-related workflows. · `.github/workflows/verify.yaml`

### Other components

- [Repository index](https://github.com/xregistry/spec/blob/main/README.md): documentation · Indexes releases and externally maintained implementations. · `README.md`
- **External implementations**: external ecosystem · Servers, CLI/codegen, viewers, and proxies live outside this repository.

## Connections

- Repository index → Core primer: directs readers to
- Core primer → Core REST contract: introduces
- Core REST contract → Core abstract model: defines
- Core abstract model → Core JSON Schema: machine-readable as
- Core JSON Schema → Core model document: validates
- Core REST contract → Endpoint registry: extended by
- Core REST contract → Message registry: extended by
- Core REST contract → Schema registry: extended by
- Endpoint registry → Domain API encodings: publishes
- Message registry → Domain API encodings: publishes
- Schema registry → Domain API encodings: publishes
- Pagination behavior → Core REST contract: augments REST behavior
- CloudEvents profile → Core REST contract: profiles
- Registry examples → Core JSON Schema: validated against
- Schema sample → CloudEvents profile: scenario for
- Local verification → Validation tools: runs
- Local verification → Schema generator: runs
- Tool dependencies → Validation tools: supports
- Schema generator → Domain API encodings: generates or verifies
- Validation tools → Core JSON Schema: checks
- GitHub Actions verification → Local verification: executes
- Domain API encodings → External implementations: consumed by
- Core REST contract → External implementations: implemented by