railiance-fabric/docs/declaration-schema.md

# Declaration Schema

Railiance Fabric declarations are small YAML documents that capture repo-local
self-description evidence. The first schema version is
`railiance.fabric/v1alpha1`.

These declarations are still supported for bootstrap and compatibility, but
they are not the long-term authority for external deployment realities,
financial fabric boundaries, tenant subfabrics, or cross-boundary utility
relations. The financial Fabric model starts from accountability roots as
described in `docs/FabricDiscoveryAndUpdate.md`.

## File Layout

Participating repositories that publish local evidence should use this layout:

```text
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:

```yaml
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:

```text
<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` | Local evidence owner for the declaration; financial Fabric ownership is resolved separately. |
| `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

```text
planned, active, deprecated, retired
```

### Environment

```text
dev, staging, prod, all
```

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

### Data Classification

```text
public, internal, confidential, restricted, secret
```

### Criticality

```text
low, medium, high, critical
```

### Auth Method

```text
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:

```yaml
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:

```yaml
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.