configuration/principle/data/metadata.data.json
configuration/principle/data/metadata.data.json is a file in GovLab Context. 340 lines of code and 0 definitions.
{
"category": "Metadata / Self-Description / Declarative Systems",
"check": {
"population": "every manifest, schema, configuration file and declared capability, and the code each one describes",
"freshness": "a verdict stands until the metadata or the code it describes changes",
"refusal": "manifest or schema validation fails when a declaration and the code disagree",
"observation": "each declaration compared with the capability, endpoint or structure found in the code",
"evidence": "none: the catalog states this check as a class, so a watched run belongs to each system that adopts it",
"authority": "none: the declaration and the code both declare the capability, so a green comparison shows that they agree and not that either is right"
},
"records": [
{
"id": "self-describing-architecture",
"name": "Self-Describing Architecture",
"definition": "A design rule that each module declares its name, version, capabilities and requirements in metadata that tools and the runtime can read.",
"type": "principle",
"scope": [
"system",
"runtime",
"integration"
],
"requires": [
"Metadata",
"Capability Declaration"
],
"reinforces": [
"Discoverability",
"Runtime Discovery"
],
"enables": [
"Plugin Architecture",
"Automation"
],
"conflicts_with": ["Hidden Runtime Behavior"],
"tensions_with": ["Metadata Drift"],
"violated_by": ["lexicon:hidden-runtime-behavior"],
"detected_by": ["undocumented runtime capability"],
"measured_by": ["metadata coverage"],
"refactored_by": [
"architecture:manifest-based-design",
"lexicon:declare-capability",
"architecture:schema-validation"
],
"enforced_by": [
"manifest validation",
"metadata tests"
],
"severity": "contextual",
"exemplar": {
"before": "const modules = [new FooModule(), new BarModule()];",
"after": "type ModuleDescriptor = { name: string; version: string; provides: readonly string[]; requires: readonly string[] };\nconst fooModule = defineModule({ name: \"foo\", version: \"1.0.0\", provides: [\"FooStore\"], requires: [\"EventBus\"] });",
"lang": "ts"
}
},
{
"id": "self-describing-api",
"name": "Self-Describing API",
"definition": "A design rule that an API publishes machine-readable descriptions of its operations, payloads and errors.",
"type": "principle",
"scope": [
"API",
"integration"
],
"requires": [
"API Contract",
"Metadata"
],
"reinforces": [
"Discoverability",
"Interoperability"
],
"enables": [
"Client Generation",
"HATEOAS-style Navigation"
],
"conflicts_with": ["Opaque API"],
"tensions_with": ["Payload Verbosity"],
"violated_by": ["lexicon:opaque-api"],
"detected_by": ["missing OpenAPI/metadata"],
"measured_by": ["API documentation/contract coverage"],
"refactored_by": [
"lexicon:define-contract",
"lexicon:declare-capability",
"lexicon:standard-error-contract"
],
"enforced_by": [
"API linting",
"docs gates"
],
"severity": "recommended",
"exemplar": {
"before": "app.post(\"/foo\", createFoo);",
"after": "const createFooApi = defineEndpoint({\n method: \"POST\",\n path: \"/foos\",\n request: CreateFooSchema,\n response: FooCreatedSchema,\n errors: FooErrorSchema,\n});",
"lang": "ts"
}
},
{
"id": "self-describing-structures",
"name": "Self-Describing Structures",
"definition": "A design rule that a data structure carries its own type tags and field names, so a reader can interpret it without outside knowledge.",
"type": "principle",
"scope": [
"data",
"runtime",
"metadata"
],
"requires": [
"Type Metadata",
"Schema"
],
"reinforces": [
"Introspection",
"Validation"
],
"enables": ["Dynamic Processing"],
"conflicts_with": ["Opaque Binary/Untyped Structures"],
"tensions_with": ["Size Overhead"],
"violated_by": ["lexicon:opaque-binary-untyped-structures"],
"detected_by": ["missing type/schema markers"],
"measured_by": ["metadata completeness"],
"refactored_by": [
"lexicon:introduce-discriminated-union",
"architecture:schema-validation",
"architecture:manifest-based-design"
],
"enforced_by": ["schema validation"],
"severity": "contextual",
"exemplar": {
"before": "const node = [\"foo\", \"foo_1\", 3, true];",
"after": "const node = { kind: \"foo\", id: \"foo_1\", count: 3, active: true } as const;",
"lang": "ts"
}
},
{
"id": "metadata-driven-design",
"name": "Metadata-Driven Design",
"definition": "An approach in which behavior such as forms, routes or plugins is generated from validated metadata instead of written case by case.",
"type": "approach",
"scope": [
"runtime",
"configuration",
"framework"
],
"requires": [
"Metadata Schema",
"Validation"
],
"reinforces": [
"Declarative Configuration",
"Runtime Discovery"
],
"enables": [
"Code Generation",
"Plugins"
],
"conflicts_with": ["Hardcoded Behavior"],
"tensions_with": ["Debuggability"],
"violated_by": [
"lexicon:unvalidated-metadata",
"lexicon:hidden-runtime-behavior"
],
"detected_by": ["metadata/config drift"],
"measured_by": [
"metadata coverage",
"config error rate"
],
"refactored_by": [
"lexicon:declare-capability",
"architecture:schema-validation",
"lexicon:configuration-schema"
],
"enforced_by": ["metadata schema tests"],
"severity": "contextual",
"exemplar": {
"before": "if (field === \"name\") renderText();\nif (field === \"count\") renderNumber();",
"after": "const fooFields = {\n name: { kind: \"text\", required: true },\n count: { kind: \"integer\", min: 0 },\n} as const;\nrenderForm(fooFields);",
"lang": "ts"
}
},
{
"id": "declarative-configuration",
"name": "Declarative Configuration",
"definition": "A design rule that a system's settings are declared as validated data, and the system configures itself from that data.",
"type": "principle",
"scope": [
"configuration",
"infrastructure",
"runtime"
],
"requires": [
"Schema Validation",
"Explicit Semantics"
],
"reinforces": [
"Predictability",
"Infrastructure as Code"
],
"enables": ["Runtime Configuration without Code Change"],
"conflicts_with": ["Hardcoded Configuration"],
"tensions_with": ["Dynamic Complexity"],
"violated_by": ["lexicon:hardcoded-behavior"],
"detected_by": ["hardcoded environment values"],
"measured_by": ["configuration externalization coverage"],
"refactored_by": [
"lexicon:externalize-configuration",
"lexicon:configuration-schema"
],
"enforced_by": [
"config linting",
"validation"
],
"severity": "recommended",
"exemplar": {
"before": "const app = new FooApp();\napp.enableCache();\napp.setRetries(3);\napp.register(new BarPlugin());",
"after": "const config = defineFooConfig({\n cache: { enabled: true },\n retries: 3,\n plugins: [\"bar\"],\n});\nconst app = FooApp.fromConfig(config);",
"lang": "ts"
}
},
{
"id": "convention-over-configuration",
"distinctFrom": [
{
"id": "architecture:self-describing-structures",
"reason": "Convention over configuration infers settings from naming and placement, while self-describing structures carry their own type tags and field names."
}
],
"name": "Convention over Configuration",
"aliases": ["Coding by Convention"],
"definition": "A design rule that a framework infers settings from stable naming and placement conventions, and explicit configuration covers only the exceptions.",
"type": "principle",
"scope": [
"framework",
"application structure"
],
"requires": ["Stable Conventions"],
"reinforces": [
"Pattern Consistency",
"Predictability"
],
"enables": ["Reduced Boilerplate"],
"conflicts_with": ["Excessive Configuration"],
"tensions_with": ["Explicitness"],
"violated_by": ["lexicon:inconsistent-conventions"],
"detected_by": ["convention deviations"],
"measured_by": ["convention compliance score"],
"refactored_by": [
"lexicon:standardize-the-interface",
"lexicon:centralize-the-rule"
],
"enforced_by": [
"scaffolding",
"lint rules"
],
"severity": "contextual",
"exemplar": {
"before": "registerHandler(\"foo\", \"./handlers/foo-handler\", \"FooHandler\");\nregisterHandler(\"bar\", \"./handlers/bar-handler\", \"BarHandler\");",
"after": "const handlers = discoverHandlers(\"./handlers/*.handler.ts\");",
"lang": "ts"
}
},
{
"id": "capability-declaration",
"name": "Capability Declaration",
"definition": "A mechanism by which a plugin or service lists the operations it supports, so callers test the list instead of probing for methods.",
"type": "mechanism",
"scope": [
"plugin",
"service",
"runtime"
],
"requires": [
"Manifest",
"Contracts"
],
"reinforces": [
"Runtime Discovery",
"Self-Description"
],
"enables": ["Dynamic Binding"],
"conflicts_with": ["Implicit Capability"],
"tensions_with": ["Declaration Drift"],
"violated_by": ["lexicon:implicit-capability"],
"detected_by": ["manifest-code mismatch"],
"measured_by": ["declared/actual capability match rate"],
"refactored_by": [
"architecture:manifest-based-design",
"lexicon:extract-role-interface"
],
"enforced_by": [
"manifest validation",
"conformance tests"
],
"severity": "recommended",
"exemplar": {
"before": "try { await plugin.exportFoo(foo); } catch (error) { if (isMissingMethod(error)) return; }",
"after": "type FooPlugin = {\n capabilities: readonly (\"read\" | \"write\" | \"export\")[];\n exportFoo?: (foo: Foo) => Promise<void>;\n};\nif (plugin.capabilities.includes(\"export\")) await plugin.exportFoo!(foo);",
"lang": "ts"
}
},
{
"id": "manifest-based-design",
"name": "Manifest-Based Design",
"definition": "A design pattern that loads modules or plugins from a validated manifest listing each entry, version and dependency.",
"type": "pattern",
"scope": [
"plugin",
"module",
"deployment"
],
"requires": ["Manifest Schema"],
"reinforces": [
"Self-Describing Architecture",
"Runtime Discovery"
],
"enables": [
"Plugin Loading",
"Capability Declaration"
],
"conflicts_with": ["Hardcoded Registration"],
"tensions_with": ["Manifest Drift"],
"violated_by": [
"lexicon:implicit-capability",
"lexicon:hidden-dependency"
],
"detected_by": [
"manifest mismatch",
"load failure"
],
"measured_by": ["manifest validation pass rate"],
"refactored_by": ["lexicon:discovery-validation"],
"enforced_by": ["CI validation"],
"severity": "contextual",
"exemplar": {
"before": "loadPlugin(\"./foo.js\");\nloadPlugin(\"./bar.js\");",
"after": "const manifest = {\n name: \"foo-suite\",\n plugins: [\n { name: \"foo\", entry: \"./foo.js\", version: \"1.0.0\" },\n { name: \"bar\", entry: \"./bar.js\", version: \"1.0.0\" },\n ],\n} as const;\nloadManifest(manifest);",
"lang": "ts"
}
}
]
}