# Metadata / Self-Description / Declarative Systems

> Every principle in this category is listed as a record.

Page: Ontology · Principles
Canonical: https://banes-lab.com/ontology#arch-category-metadata-self-description-declarative-systems

Every principle in this category is listed as a record. Each record carries its kind, its severity, the scopes it applies at and the layer it lives in, then the edge relations that join it to other records, the records that point back at it, the contracts that answer to it and the tensions it takes part in. The descriptors say how it is violated, detected, measured, repaired and enforced. Where the record carries one, an exemplar shows the shape before and after the principle is applied.

Relations diagram

The relations inside this category.

```mermaid
flowchart LR
n_self_describing_architecture["Self-Describing Architecture"]
n_self_describing_api["Self-Describing API"]
n_self_describing_structures["Self-Describing Structures"]
n_metadata_driven_design["Metadata-Driven Design"]
n_declarative_configuration["Declarative Configuration"]
n_convention_over_configuration["Convention over Configuration"]
n_capability_declaration["Capability Declaration"]
n_manifest_based_design["Manifest-Based Design"]
n_self_describing_architecture --> n_capability_declaration
n_metadata_driven_design --> n_declarative_configuration
n_manifest_based_design --> n_self_describing_architecture
n_manifest_based_design --> n_capability_declaration
```

### Self-Describing Architecture

- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Severity: contextual
- Scope: system, runtime, integration
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Metadata](https://banes-lab.com/records/lex/metadata.md), [Capability Declaration](https://banes-lab.com/records/arch/capability-declaration.md)

Reinforces
[Discoverability](https://banes-lab.com/records/lex/discoverability.md), [Runtime Discovery](https://banes-lab.com/records/arch/runtime-discovery.md)

Enables
[Plugin Architecture](https://banes-lab.com/records/arch/plugin-architecture.md), [Automation](https://banes-lab.com/records/lex/automation.md)

In tension with
[Metadata Drift](https://banes-lab.com/records/lex/metadata-drift.md)

Conflicts with
[Hidden Runtime Behavior](https://banes-lab.com/records/lex/hidden-runtime-behavior.md)

Referenced by
[Manifest-Based Design](https://banes-lab.com/records/arch/manifest-based-design.md)

Tensions
[Self-Describing Architecture Metadata Drift](https://banes-lab.com/records/tension/metadata-drift-self-describing-architecture.md)

Violated by
behavior not represented in metadata/contracts

Detected by
undocumented runtime capability

Measured by
metadata coverage

Refactored by
Add Manifest, Add Metadata, Add Schema

Enforced by
manifest validation, metadata tests

Before

```typescript
const modules = [new FooModule(), new BarModule()];
```

After

```typescript
type ModuleDescriptor = { name: string; version: string; provides: readonly string[]; requires: readonly string[] };
const fooModule = defineModule({ name: "foo", version: "1.0.0", provides: ["FooStore"], requires: ["EventBus"] });
```

### Self-Describing API

- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Severity: recommended
- Scope: API, integration
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[API Contract](https://banes-lab.com/records/arch/api-contract.md), [Metadata](https://banes-lab.com/records/lex/metadata.md)

Reinforces
[Discoverability](https://banes-lab.com/records/lex/discoverability.md), [Interoperability](https://banes-lab.com/records/arch/interoperability.md)

Enables
[Client Generation](https://banes-lab.com/records/lex/client-generation.md), [HATEOAS-style Navigation](https://banes-lab.com/records/lex/hateoas-style-navigation.md)

In tension with
[Payload Verbosity](https://banes-lab.com/records/lex/payload-verbosity.md)

Conflicts with
[Opaque API](https://banes-lab.com/records/lex/opaque-api.md)

Tensions
[Self-Describing API Payload Verbosity](https://banes-lab.com/records/tension/payload-verbosity-self-describing-api.md)

Violated by
undocumented endpoints, opaque error responses

Detected by
missing OpenAPI/metadata

Measured by
API documentation/contract coverage

Refactored by
Add OpenAPI, Add Metadata, Normalize Responses

Enforced by
API linting, docs gates

Before

```typescript
app.post("/foo", createFoo);
```

After

```typescript
const createFooApi = defineEndpoint({
method: "POST",
path: "/foos",
request: CreateFooSchema,
response: FooCreatedSchema,
errors: FooErrorSchema,
});
```

### Self-Describing Structures

- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Severity: contextual
- Scope: data, runtime, metadata
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Type Metadata](https://banes-lab.com/records/lex/type-metadata.md), [Schema](https://banes-lab.com/records/lex/schema.md)

Reinforces
[Introspection](https://banes-lab.com/records/arch/introspection.md), [Validation](https://banes-lab.com/records/arch/validation.md)

Enables
[Dynamic Processing](https://banes-lab.com/records/lex/dynamic-processing.md)

In tension with
[Size Overhead](https://banes-lab.com/records/lex/size-overhead.md)

Conflicts with
[Opaque Binary/Untyped Structures](https://banes-lab.com/records/lex/opaque-binary-untyped-structures.md)

Referenced by
[Derived Naming Registry](https://banes-lab.com/records/arch/derived-naming-registry.md)

Tensions
[Self-Describing Structures Size Overhead](https://banes-lab.com/records/tension/self-describing-structures-size-overhead.md)

Violated by
data requiring external hidden assumptions

Detected by
missing type/schema markers

Measured by
metadata completeness

Refactored by
Add Type Tags, Add Schema, Add Manifest

Enforced by
[schema validation](https://banes-lab.com/records/arch/schema-validation.md)

Before

```typescript
const node = ["foo", "foo_1", 3, true];
```

After

```typescript
const node = { kind: "foo", id: "foo_1", count: 3, active: true } as const;
```

### Metadata-Driven Design

- Kind: [approach](https://banes-lab.com/records/kind/approach.md)
- Severity: contextual
- Scope: runtime, configuration, framework
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Metadata Schema](https://banes-lab.com/records/lex/metadata-schema.md), [Validation](https://banes-lab.com/records/arch/validation.md)

Reinforces
[Declarative Configuration](https://banes-lab.com/records/arch/declarative-configuration.md), [Runtime Discovery](https://banes-lab.com/records/arch/runtime-discovery.md)

Enables
[Code Generation](https://banes-lab.com/records/lex/code-generation.md), [Plugins](https://banes-lab.com/records/lex/plugins.md)

In tension with
[Debuggability](https://banes-lab.com/records/lex/debuggability.md)

Conflicts with
[Hardcoded Behavior](https://banes-lab.com/records/lex/hardcoded-behavior.md)

Referenced by
[Model-Driven Architecture](https://banes-lab.com/records/arch/model-driven-architecture.md)

Tensions
[Metadata-Driven Design Debuggability](https://banes-lab.com/records/tension/debuggability-metadata-driven-design.md)

Violated by
unvalidated metadata, hidden magic

Detected by
metadata/config drift

Measured by
metadata coverage, config error rate

Refactored by
Extract Metadata, Add Schema, Validate Config

Enforced by
metadata schema tests

Before

```typescript
if (field === "name") renderText();
if (field === "count") renderNumber();
```

After

```typescript
const fooFields = {
name: { kind: "text", required: true },
count: { kind: "integer", min: 0 },
} as const;
renderForm(fooFields);
```

### Declarative Configuration

- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Severity: recommended
- Scope: configuration, infrastructure, runtime
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Schema Validation](https://banes-lab.com/records/arch/schema-validation.md), [Explicit Semantics](https://banes-lab.com/records/lex/explicit-semantics.md)

Reinforces
[Predictability](https://banes-lab.com/records/arch/predictability.md), [Infrastructure as Code](https://banes-lab.com/records/arch/infrastructure-as-code.md)

Enables
[Runtime Configuration without Code Change](https://banes-lab.com/records/lex/runtime-configuration-without-code-change.md)

In tension with
[Dynamic Complexity](https://banes-lab.com/records/lex/dynamic-complexity.md)

Conflicts with
[Hardcoded Configuration](https://banes-lab.com/records/arch/hardcoded-configuration.md)

Referenced by
[Metadata-Driven Design](https://banes-lab.com/records/arch/metadata-driven-design.md), [Domain-Specific Language (DSL)](https://banes-lab.com/records/arch/domain-specific-language.md), [Infrastructure as Code](https://banes-lab.com/records/arch/infrastructure-as-code.md)

Tensions
[Declarative Configuration Dynamic Complexity](https://banes-lab.com/records/tension/declarative-configuration-dynamic-complexity.md)

Violated by
behavior hidden in code constants

Detected by
hardcoded environment values

Measured by
configuration externalization coverage

Refactored by
Extract Config, Add Config Schema

Enforced by
config linting, [validation](https://banes-lab.com/records/arch/validation.md)

Before

```typescript
const app = new FooApp();
app.enableCache();
app.setRetries(3);
app.register(new BarPlugin());
```

After

```typescript
const config = defineFooConfig({
cache: { enabled: true },
retries: 3,
plugins: ["bar"],
});
const app = FooApp.fromConfig(config);
```

### Convention over Configuration

- Kind: [principle](https://banes-lab.com/records/kind/principle.md)
- Severity: contextual
- Scope: framework, application structure
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Stable Conventions](https://banes-lab.com/records/lex/stable-conventions.md)

Reinforces
[Pattern Consistency](https://banes-lab.com/records/arch/pattern-consistency.md), [Predictability](https://banes-lab.com/records/arch/predictability.md)

Enables
[Reduced Boilerplate](https://banes-lab.com/records/lex/reduced-boilerplate.md)

In tension with
[Explicitness](https://banes-lab.com/records/lex/explicitness.md)

Conflicts with
[Excessive Configuration](https://banes-lab.com/records/lex/excessive-configuration.md)

Referenced by
[Derived Naming Registry](https://banes-lab.com/records/arch/derived-naming-registry.md)

Tensions
[Convention over Configuration Explicitness](https://banes-lab.com/records/tension/convention-over-configuration-explicitness.md)

Violated by
inconsistent project conventions

Detected by
convention deviations

Measured by
convention compliance score

Refactored by
Normalize Structure, Remove Redundant Config

Enforced by
scaffolding, lint rules

Before

```typescript
registerHandler("foo", "./handlers/foo-handler", "FooHandler");
registerHandler("bar", "./handlers/bar-handler", "BarHandler");
```

After

```typescript
const handlers = discoverHandlers("./handlers/*.handler.ts");
```

### Capability Declaration

- Kind: [mechanism](https://banes-lab.com/records/kind/mechanism.md)
- Severity: recommended
- Scope: plugin, service, runtime
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Manifest](https://banes-lab.com/records/lex/manifest.md), [Contracts](https://banes-lab.com/records/lex/contracts.md)

Reinforces
[Runtime Discovery](https://banes-lab.com/records/arch/runtime-discovery.md), [Self-Description](https://banes-lab.com/records/lex/self-description.md)

Enables
[Dynamic Binding](https://banes-lab.com/records/arch/dynamic-binding.md)

In tension with
[Declaration Drift](https://banes-lab.com/records/lex/declaration-drift.md)

Conflicts with
[Implicit Capability](https://banes-lab.com/records/lex/implicit-capability.md)

Referenced by
[Self-Describing Architecture](https://banes-lab.com/records/arch/self-describing-architecture.md), [Manifest-Based Design](https://banes-lab.com/records/arch/manifest-based-design.md)

Tensions
[Capability Declaration Declaration Drift](https://banes-lab.com/records/tension/capability-declaration-declaration-drift.md)

Violated by
capability exists but is undocumented/unregistered

Detected by
manifest-code mismatch

Measured by
declared/actual capability match rate

Refactored by
Add Manifest Entry, Add Capability Interface

Enforced by
manifest validation, conformance tests

Before

```typescript
try { await plugin.exportFoo(foo); } catch (error) { if (isMissingMethod(error)) return; }
```

After

```typescript
type FooPlugin = {
capabilities: readonly ("read" | "write" | "export")[];
exportFoo?: (foo: Foo) => Promise<void>;
};
if (plugin.capabilities.includes("export")) await plugin.exportFoo!(foo);
```

### Manifest-Based Design

- Kind: [pattern](https://banes-lab.com/records/kind/pattern.md)
- Severity: contextual
- Scope: plugin, module, deployment
- Layer: [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)

Details

Requires
[Manifest Schema](https://banes-lab.com/records/lex/manifest-schema.md)

Reinforces
[Self-Describing Architecture](https://banes-lab.com/records/arch/self-describing-architecture.md), [Runtime Discovery](https://banes-lab.com/records/arch/runtime-discovery.md)

Enables
[Plugin Loading](https://banes-lab.com/records/lex/plugin-loading.md), [Capability Declaration](https://banes-lab.com/records/arch/capability-declaration.md)

In tension with
[Manifest Drift](https://banes-lab.com/records/lex/manifest-drift.md)

Conflicts with
[Hardcoded Registration](https://banes-lab.com/records/lex/hardcoded-registration.md)

Tensions
[Manifest-Based Design Manifest Drift](https://banes-lab.com/records/tension/manifest-based-design-manifest-drift.md)

Violated by
undeclared dependencies/capabilities

Detected by
manifest mismatch, load failure

Measured by
manifest validation pass rate

Refactored by
Add Manifest, Validate Manifest, Generate Manifest

Enforced by
CI validation

Before

```typescript
loadPlugin("./foo.js");
loadPlugin("./bar.js");
```

After

```typescript
const manifest = {
name: "foo-suite",
plugins: [
{ name: "foo", entry: "./foo.js", version: "1.0.0" },
{ name: "bar", entry: "./bar.js", version: "1.0.0" },
],
} as const;
loadManifest(manifest);
```

## Links to

- [principle](https://banes-lab.com/records/kind/principle.md)
- [Declarative Core](https://banes-lab.com/records/layer/declarative-core.md)
- [Metadata](https://banes-lab.com/records/lex/metadata.md)
- [Capability Declaration](https://banes-lab.com/records/arch/capability-declaration.md)
- [Discoverability](https://banes-lab.com/records/lex/discoverability.md)
- [Runtime Discovery](https://banes-lab.com/records/arch/runtime-discovery.md)
- [Plugin Architecture](https://banes-lab.com/records/arch/plugin-architecture.md)
- [Automation](https://banes-lab.com/records/lex/automation.md)
- [Metadata Drift](https://banes-lab.com/records/lex/metadata-drift.md)
- [Hidden Runtime Behavior](https://banes-lab.com/records/lex/hidden-runtime-behavior.md)
- [Manifest-Based Design](https://banes-lab.com/records/arch/manifest-based-design.md)
- [Self-Describing Architecture / Metadata Drift](https://banes-lab.com/records/tension/metadata-drift-self-describing-architecture.md)
- [API Contract](https://banes-lab.com/records/arch/api-contract.md)
- [Interoperability](https://banes-lab.com/records/arch/interoperability.md)
- [Client Generation](https://banes-lab.com/records/lex/client-generation.md)
- [HATEOAS-style Navigation](https://banes-lab.com/records/lex/hateoas-style-navigation.md)
- [Payload Verbosity](https://banes-lab.com/records/lex/payload-verbosity.md)
- [Opaque API](https://banes-lab.com/records/lex/opaque-api.md)
- [Self-Describing API / Payload Verbosity](https://banes-lab.com/records/tension/payload-verbosity-self-describing-api.md)
- [Type Metadata](https://banes-lab.com/records/lex/type-metadata.md)
- [Schema](https://banes-lab.com/records/lex/schema.md)
- [Introspection](https://banes-lab.com/records/arch/introspection.md)
- [Validation](https://banes-lab.com/records/arch/validation.md)
- [Dynamic Processing](https://banes-lab.com/records/lex/dynamic-processing.md)
- [Size Overhead](https://banes-lab.com/records/lex/size-overhead.md)
- [Opaque Binary/Untyped Structures](https://banes-lab.com/records/lex/opaque-binary-untyped-structures.md)
- [Derived Naming Registry](https://banes-lab.com/records/arch/derived-naming-registry.md)
- [Self-Describing Structures / Size Overhead](https://banes-lab.com/records/tension/self-describing-structures-size-overhead.md)
- [Schema Validation](https://banes-lab.com/records/arch/schema-validation.md)
- [approach](https://banes-lab.com/records/kind/approach.md)
- [Metadata Schema](https://banes-lab.com/records/lex/metadata-schema.md)
- [Declarative Configuration](https://banes-lab.com/records/arch/declarative-configuration.md)
- [Code Generation](https://banes-lab.com/records/lex/code-generation.md)
- [Plugins](https://banes-lab.com/records/lex/plugins.md)
- [Debuggability](https://banes-lab.com/records/lex/debuggability.md)
- [Hardcoded Behavior](https://banes-lab.com/records/lex/hardcoded-behavior.md)
- [Model-Driven Architecture](https://banes-lab.com/records/arch/model-driven-architecture.md)
- [Metadata-Driven Design / Debuggability](https://banes-lab.com/records/tension/debuggability-metadata-driven-design.md)
- [Explicit Semantics](https://banes-lab.com/records/lex/explicit-semantics.md)
- [Predictability](https://banes-lab.com/records/arch/predictability.md)
- [Infrastructure as Code](https://banes-lab.com/records/arch/infrastructure-as-code.md)
- [Runtime Configuration without Code Change](https://banes-lab.com/records/lex/runtime-configuration-without-code-change.md)
- [Dynamic Complexity](https://banes-lab.com/records/lex/dynamic-complexity.md)
- [Hardcoded Configuration](https://banes-lab.com/records/arch/hardcoded-configuration.md)
- [Metadata-Driven Design](https://banes-lab.com/records/arch/metadata-driven-design.md)
- [Domain-Specific Language (DSL)](https://banes-lab.com/records/arch/domain-specific-language.md)
- [Declarative Configuration / Dynamic Complexity](https://banes-lab.com/records/tension/declarative-configuration-dynamic-complexity.md)
- [Stable Conventions](https://banes-lab.com/records/lex/stable-conventions.md)
- [Pattern Consistency](https://banes-lab.com/records/arch/pattern-consistency.md)
- [Reduced Boilerplate](https://banes-lab.com/records/lex/reduced-boilerplate.md)
- [Explicitness](https://banes-lab.com/records/lex/explicitness.md)
- [Excessive Configuration](https://banes-lab.com/records/lex/excessive-configuration.md)
- [Convention over Configuration / Explicitness](https://banes-lab.com/records/tension/convention-over-configuration-explicitness.md)
- [mechanism](https://banes-lab.com/records/kind/mechanism.md)
- [Manifest](https://banes-lab.com/records/lex/manifest.md)
- [Contracts](https://banes-lab.com/records/lex/contracts.md)
- [Self-Description](https://banes-lab.com/records/lex/self-description.md)
- [Dynamic Binding](https://banes-lab.com/records/arch/dynamic-binding.md)
- [Declaration Drift](https://banes-lab.com/records/lex/declaration-drift.md)
- [Implicit Capability](https://banes-lab.com/records/lex/implicit-capability.md)
- [Self-Describing Architecture](https://banes-lab.com/records/arch/self-describing-architecture.md)
- [Capability Declaration / Declaration Drift](https://banes-lab.com/records/tension/capability-declaration-declaration-drift.md)
- [pattern](https://banes-lab.com/records/kind/pattern.md)
- [Manifest Schema](https://banes-lab.com/records/lex/manifest-schema.md)
- [Plugin Loading](https://banes-lab.com/records/lex/plugin-loading.md)
- [Manifest Drift](https://banes-lab.com/records/lex/manifest-drift.md)
- [Hardcoded Registration](https://banes-lab.com/records/lex/hardcoded-registration.md)
- [Manifest-Based Design / Manifest Drift](https://banes-lab.com/records/tension/manifest-based-design-manifest-drift.md)

## Linked from

- [The layer topology](https://banes-lab.com/ontology/schema/the-layer-topology.md)
- [The membership](https://banes-lab.com/ontology/schema/the-membership.md)