railiance-fabric/docs/declaration-schema.md

Declaration Schema

Railiance Fabric declarations are small YAML documents owned by the repository that provides or consumes the declared thing. The first schema version is railiance.fabric/v1alpha1.

File Layout

Participating repositories should use this layout:

fabric/
  services/*.yaml
  capabilities/*.yaml
  interfaces/*.yaml
  dependencies/*.yaml
  bindings/*.yaml

Railiance Fabric itself keeps reusable schemas in schemas/ and examples in examples/declarations/.

Shared Shape

Every declaration has:

apiVersion: railiance.fabric/v1alpha1
kind: ServiceDeclaration
metadata:
  id: railiance-platform.openbao
  name: OpenBao
  owner: railiance-platform
  repo: railiance-platform
  domain: railiance
spec:
  lifecycle: active
  environments: [dev, staging, prod]

metadata.id is the stable graph identifier. Use lower-case dotted IDs that begin with the owning repo slug when possible:

<repo>.<service>
<repo>.<service>.<capability>
<repo>.<service>.<interface>
<repo>.<consumer>.<dependency>

Shared Fields

Field	Meaning
apiVersion	Schema API version. Currently railiance.fabric/v1alpha1.
kind	Declaration kind: service, capability, interface, dependency, or binding assertion.
metadata.id	Stable graph identifier used for references and bindings.
metadata.name	Human-readable display name.
metadata.owner	Owning team, repo, or domain owner.
metadata.repo	Repo slug that owns the declaration.
metadata.domain	Domain slug, such as railiance or custodian.
metadata.source_links	Optional source pointers to docs, code, manifests, ADRs, or workplans.
spec.lifecycle	planned, active, deprecated, or retired.
spec.environments	One or more of dev, staging, prod, or all.

Declaration Kinds

ServiceDeclaration

A deployable or callable unit produced by a repo.

Required type-specific fields:

• spec.description

Optional relationship fields:

• spec.service_type
• spec.provides_capabilities
• spec.exposes_interfaces

Schema: schemas/service.schema.yaml

CapabilityDeclaration

A stable semantic ability that consumers depend on.

Required type-specific fields:

• spec.description
• spec.capability_type
• spec.service_id
• spec.criticality
• spec.data_classification

Optional relationship fields:

• spec.interface_ids
• spec.compatibility

Schema: schemas/capability.schema.yaml

spec.capability_type should match a type in catalog/capability-types.yaml. Unknown types are allowed by the document schema but should fail graph validation.

InterfaceDeclaration

A concrete integration surface through which a capability is consumed.

Required type-specific fields:

• spec.description
• spec.interface_type
• spec.version
• spec.service_id
• spec.auth.method
• spec.data_classification

Optional relationship fields:

• spec.capability_ids
• spec.endpoint
• spec.auth.audience
• spec.auth.scopes
• spec.compatibility

Schema: schemas/interface.schema.yaml

spec.interface_type should match a type in catalog/interface-types.yaml. Unknown types are allowed by the document schema but should fail graph validation.

DependencyDeclaration

A consumer's declared requirement for a capability or interface.

Required type-specific fields:

• spec.consumer_service_id
• spec.requires.capability_type
• spec.criticality
• spec.data_classification

Optional constraint fields:

• spec.requires.capability_id
• spec.interface.type
• spec.interface.version_constraint
• spec.auth.method
• spec.fallback
• spec.compatibility

Schema: schemas/dependency.schema.yaml

spec.requires.capability_type and spec.interface.type should match the type catalogs. Unknown types are allowed by the document schema but should fail graph validation.

BindingAssertion

A source-controlled assertion that resolves a dependency to a provider capability and, optionally, a provider interface. Most bindings should be computed by the graph loader; binding assertions are for overrides, disputes, or planned relationships that need an explicit record.

Required type-specific fields:

• spec.dependency_id
• spec.provider_capability_id
• spec.status
• spec.rationale

Optional relationship fields:

• spec.provider_interface_id
• spec.compatibility

Schema: schemas/binding.schema.yaml

Shared Value Sets

Lifecycle

planned, active, deprecated, retired

Environment

dev, staging, prod, all

Use all only when the declaration truly applies across every environment.

Data Classification

public, internal, confidential, restricted, secret

Criticality

low, medium, high, critical

Auth Method

none, oidc, jwt, mtls, kubernetes_service_account, openbao_token,
static_secret, database_role, sts_token, api_key, unknown

unknown is allowed for discovery-stage declarations but should not remain on active production dependencies.

Compatibility

The optional compatibility object records machine-checkable or human-reviewed constraints:

compatibility:
  version: "v1"
  requires:
    - "decision-envelope >=1.0 <2.0"
  compatible_with:
    - "flex-auth.decision-api.v1"
  breaks:
    - "decision-envelope v0"
  notes: "Envelope v1 is required for tenant-scoped decisions."

T05 will decide which compatibility fields are advisory and which should fail validation.

Source Links

Use metadata.source_links when a declaration is based on a concrete source:

source_links:
  - label: OpenBao Helm values
    path: charts/openbao/values.yaml
  - label: Runtime secrets workplan
    url: https://example.invalid/workplans/openbao-runtime-secrets

At least one source link is recommended for active declarations. T05 will make source-link requirements stricter for active production dependencies.