generated from coulomb/repo-seed
Establish Railiance Fabric graph model
This commit is contained in:
252
docs/declaration-schema.md
Normal file
252
docs/declaration-schema.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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:
|
||||
|
||||
```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` | 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
|
||||
|
||||
```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.
|
||||
Reference in New Issue
Block a user