AIFC-091: Schemas and Metadata Registry

Status: Draft 0.1 Standard: AI-First Community Standard Abbreviation: AIFC Builds on:

• AIFC-001 Core Concepts
• AIFC-010 Knowledge Structure
• AIFC-011 Operational DNA
• AIFC-012 Metadata and Markdown
• AIFC-013 Human and AI Readable Content
• AIFC-050 Community Interface
• AIFC-060 Knowledge Security
• AIFC-061 Access Control
• AIFC-062 Agent Permissions
• AIFC-063 Auditability
• AIFC-064 Data Classification
• AIFC-080 Compliance Levels
• AIFC-090 Agent-Actionable Standard

Purpose of this document: To define Schemas and Metadata Registry as the central catalogue of structured artefacts, metadata, fields, types, statuses, relationships, and validation rules used in the AIFC knowledge base. This document describes how AIFC artefacts should be structured so that they remain readable for people, usable for AI agents, and verifiable by software.

1. Purpose of this document

This document defines Schemas and Metadata Registry.

The AIFC knowledge base should not be only a folder of text files. It should be a living system of artefacts.

These artefacts may include purpose statement, values record, decision record, change proposal, feedback signal, workflow definition, human skill, AI skill, agent permissions, access policy, classification record, AI-NDA Boundary, audit event, compliance assessment, ghost AI company risk assessment, Operational DNA record, interface record, incident record, and retrospective record.

For people, AI agents, and software to work with them consistently, they need a shared structural foundation.

Schemas and Metadata Registry defines this foundation.

2. Core principle

The core principle of this document is:

AIFC artefacts must be structured enough for agents and software, but readable enough for humans.

AIFC states:

Do not turn knowledge into unreadable data.
Do not leave knowledge as unstructured prose.

The registry should protect the balance between human readability and machine usability.

3. Definition

Schemas and Metadata Registry is the central catalogue of schemas, metadata, artefact types, required fields, recommended fields, statuses, relationships, validation rules, and versions used in the AIFC standard and its implementations.

The registry defines what artefacts exist, how they are named, what metadata they have, what statuses they may take, what relationships they may have, which fields are required, which fields are recommended, what rules are validated, how artefacts are versioned, how metadata are inherited, how compatibility is handled, how they map to the Human Cockpit Layer, and how AI agents use them.

Minimum requirement

An AIFC implementation must have a defined catalogue of key artefacts and their basic metadata.

4. Why schemas matter

Without schemas, chaos emerges.

Every AI agent starts creating a slightly different format. Every team starts using different field names. Every project gets different statuses. Every validator expects a different structure.

The result is lower trust, higher attention debt, worse agentic usability, weaker validation, worse migration, worse audit, worse compliance, more manual work, and more AI waste.

Schemas do not exist to make writing harder. They exist so the community can maintain order while it grows.

Minimum requirement

Critical repeatable artefacts must have stable structure.

5. Why metadata matter

Metadata gives knowledge operational context.

Text says what the content is. Metadata says what it is, who owns it, what status it has, how sensitive it is, whether AI may read it, whether it has been reviewed, what relationships it has, when it should be reviewed, whether it is active or draft, whether it is public or Operational DNA, and whether it requires approval.

Without metadata, people and agents guess. Guessing creates risk.

Minimum requirement

Critical knowledge artefacts must have metadata sufficient for ownership, status, classification, and review.

6. Registry as source of structure

Schemas and Metadata Registry is the source of structure.

It defines structure for other AIFC artefacts. It is not necessarily the source of truth for the content of a specific community. It is the source of truth for format and structural rules.

Example:

AIFC Registry defines what a Decision Record should contain.

Community source of truth contains actual Decision Records.

Minimum requirement

The community must distinguish the standard registry from its own community content.

7. Human-readable schema

A schema must not be only technical JSON.

An AIFC schema must be human-understandable. It should contain artefact name, purpose, when it is used, who owns it, required fields, recommended fields, examples, anti-patterns, links to standard requirements, validation rules, and AI usage notes.

Minimum requirement

Every key schema must have a human-readable description of purpose and use.

8. Agent-actionable schema

A schema must be usable by AI agents.

An agent must know when to create the artefact, which fields to fill, which fields it must not invent, when to mark uncertainty, when to create a gap, when to escalate, what output format to use, how to verify required fields, how to respect classification, and when to request human review.

Minimum requirement

Key schemas must contain instructions or references for agentic use.

9. Software-verifiable schema

A schema must be partially software-verifiable.

Software can verify required fields, data types, allowed values, references, status transitions, classification rules, review dates, owner existence, missing approvals, expired validity, and broken links.

Software cannot fully verify meaning. But it can prevent formal chaos.

Minimum requirement

Critical schemas must have a software-verifiable part where practical.

10. Recommended registry structure

Recommended registry structure:

/agent-actionable
  /schemas
    community-profile.schema.md
    purpose-record.schema.md
    values-record.schema.md
    decision-record.schema.md
    change-proposal.schema.md
    feedback-signal.schema.md
    workflow.schema.md
    human-skill.schema.md
    ai-skill.schema.md
    agent-permissions.schema.md
    access-policy.schema.md
    classification.schema.md
    ai-nda-boundary.schema.md
    audit-event.schema.md
    compliance-assessment.schema.md
    incident-record.schema.md
    ghost-risk-assessment.schema.md
  /metadata
    common-fields.md
    lifecycle-statuses.md
    classification-levels.md
    relationship-types.md
    severity-levels.md
  /validation-rules
  /examples

Minimum requirement

The registry must have stable location and naming.

11. Common metadata fields

AIFC recommends common metadata fields.

Basic set:

id:
title:
type:
status:
owner:
classification:
created_at:
updated_at:
last_reviewed:
review_cycle:
source:
related_artefacts:
ai_generated:
human_reviewed:
approved_by:

Not every artefact must use all fields. Shared fields reduce chaos.

Minimum requirement

The registry must define common metadata fields and their meaning.

12. Stable identity

Artefacts need stable identity.

AIFC does not recommend relying only on visible sequential numbers in text. Identity should remain stable even if an artefact moves.

Options include UUID, short stable ID, slug plus namespace, repository path plus internal ID, or generated non-sequential ID.

Movement or reordering must not change identity.

Minimum requirement

Critical artefacts must have stable identity independent of order in a file.

13. Type

The type field states what artefact a block or file represents.

Examples:

purpose_record
values_record
decision_record
change_proposal
feedback_signal
workflow
human_skill
ai_skill
agent_permissions
audit_event
classification
compliance_assessment

Type may be inherited from file or folder name, but override must be possible if the artefact changes nature.

Minimum requirement

Every critical artefact must have an explicit or inherited type.

14. Status

Status states the lifecycle state of an artefact.

AIFC recommends at least:

draft
proposed
under_review
approved
active
deprecated
archived
rejected

Status is critical for AI. AI must not treat draft as active rule.

Minimum requirement

Critical artefacts must have status or inherit it from context.

15. Owner

Owner states who is responsible for the artefact.

Owner may be a person, role, team, community, or governance body.

Owner does not mean sole author. Owner means accountability.

Minimum requirement

Critical artefacts must have an owner or clear owning role.

16. Classification

Classification states how sensitive an artefact is.

Recommended values:

public
internal
restricted
operational_dna

Classification affects access, AI processing, export, audit, public release, and retention.

Minimum requirement

Critical artefacts must have classification or inherit it from context.

17. AI access metadata

Metadata must state whether and how AI may process the artefact.

Example:

ai_access:
  allowed: true
  allowed_tools:
  memory_allowed: false
  training_allowed: false
  requires_ai_nda_boundary: true
  human_review_required: true

Minimum requirement

Restricted or Operational DNA artefacts must have an AI processing rule or inherit it from classification.

18. Review metadata

Review metadata states when and how an artefact is checked.

Example:

review:
  last_reviewed:
  next_review:
  review_cycle:
  reviewer:
  review_status:

Review matters for aging, compliance, security, AI skills, public claims, agent permissions, and fallback.

Minimum requirement

Critical artefacts must have a review rule or review trigger.

19. Approval metadata

Approval metadata states who approved something.

Example:

approval:
  required: true
  approved_by:
  approved_at:
  approval_scope:
  expires_at:

Approval is needed for active decisions, public claims, AI agent activation, restricted export, classification downgrade, AI-NDA Boundary changes, and high-risk AI outputs.

Minimum requirement

Artefacts that change active governance or public commitments must have approval metadata.

20. Lineage metadata

Lineage states where an artefact came from.

Example:

lineage:
  source_artefacts:
  generated_by:
  ai_model:
  prompt_reference:
  human_review:
  derived_from:

Lineage matters for AI-generated content, derived knowledge, and audit.

Minimum requirement

Critical AI-generated artefacts must have basic lineage or reference to source evidence.

21. Relationship metadata

Artefacts are connected.

Example relationship types:

implements
depends_on
supersedes
conflicts_with
derived_from
references
requires_review_of
owned_by
affects
mitigates
validates

Relationship metadata helps people and agents understand context.

Minimum requirement

Critical relationships between decisions, workflows, risks, agents, and skills must be traceable.

22. Lifecycle statuses

The registry must define lifecycle statuses.

Example for change proposal:

draft
proposed
triaged
under_review
accepted
rejected
deferred
implemented
verified
closed

Example for agent:

draft
proposed
active
paused
revoked
retired
archived

Minimum requirement

Every artefact with governed lifecycle must have defined status values and transitions.

23. Status transitions

Status transitions define how states may change.

Example:

draft -> under_review -> approved -> active
active -> deprecated -> archived

Invalid transition:

draft -> active without approval

Minimum requirement

Critical status transitions must be defined or validatable.

24. Required vs recommended fields

A schema must distinguish required, recommended, optional, and conditional fields.

Example:

agent_permissions.owner = required
agent_permissions.memory_allowed = required if agent has memory
agent_permissions.tool_permissions = required if agent uses tools

Minimum requirement

Every schema must clearly distinguish required, recommended, and conditional fields.

25. Conditional metadata

Some metadata are required only under certain conditions.

Examples:

• if classification = restricted, access rule is required
• if ai_generated = true, review status is required
• if public_claim = true, approval is required
• if agent_tool_access = true, agent permissions are required
• if critical_workflow = true, fallback is required

Minimum requirement

The registry must define conditional metadata rules for critical situations.

26. Metadata inheritance

Metadata may be inherited.

For example, folder /restricted sets default classification, file ai-skills sets type, workspace sets owner, workflow sets review cycle, and registry sets default AI processing rule.

Inheritance reduces manual work, but it must be transparent.

Minimum requirement

Metadata inheritance must be explicit and override must be traceable.

27. Metadata override

Override changes an inherited value.

For example, an artefact in an internal folder may be restricted, a generic skill may contain Operational DNA, a public document may have a restricted draft, and an AI-generated summary may be more sensitive than its sources.

Override must be reviewable.

Minimum requirement

Override of critical metadata, especially classification and AI access, must be auditable.

28. Schema versioning

Schemas will change.

Every schema must have a version.

Example:

schema:
  name: agent_permissions
  version: 0.1
  status: draft

Version matters for validation, migration, compatibility, agent skills, cockpit, and compliance.

Minimum requirement

Every critical schema must have version and status.

29. Migration

Schema changes may require migration.

Migration notes should state what changed, why, impact, how to migrate old artefacts, whether the change is breaking, how success is verified, and how long the old version is supported.

Minimum requirement

Breaking schema changes must include migration guidance.

30. Schema status

Schemas themselves have lifecycle.

Recommended statuses:

draft
experimental
active
deprecated
retired

An AI agent must know that a draft schema is not stable.

Minimum requirement

Registry schemas must have lifecycle status.

31. Registry governance

The registry must have governance.

It must be clear who may propose new schema, who approves changes, how breaking changes are handled, how compatibility is maintained, how examples are added, how fields are deprecated, how conflicts are resolved, and how standard requirements are mapped.

Minimum requirement

Schemas and Metadata Registry must have owner and change governance.

32. Registry and Human Cockpit Layer

The Human Cockpit Layer may use the registry to create UI.

The schema may define what form to show, what field is required, what help text to show, what warnings to display, what workflow to start, and what approval to require.

The cockpit is then guided by the standard, not improvised.

Minimum requirement

Schemas should support human-readable forms and cockpit views where practical.

33. Registry and AI agents

AI agents use the registry to know how to create artefacts.

An agent should load the schema, fill required fields, mark uncertainty, avoid inventing missing evidence, create gaps, request review, respect status, and respect classification.

Minimum requirement

AI agents creating AIFC artefacts must follow the relevant schema or explain deviations.

34. Registry and validation

Validation rules come from schemas.

Example:

Schema says owner is required.
Validation checks owner exists.

Validation should not be separate from the registry.

Minimum requirement

Validation rules must reference schema fields and standard requirements.

35. Registry and compliance

Compliance assessment may use the registry.

Examples include Minimal AIFC Compliance assessment schema, Compliance gap schema, Certification report schema, and Evidence reference schema.

This enables comparable assessments.

Minimum requirement

Compliance artefacts must have standardized structure.

36. Registry and portability

The registry must support portability.

This means text-readable formats, export, versioning, clear field names, limited vendor-specific fields, mapping to other tools, and implementation in different environments.

Minimum requirement

Core schemas must be portable and not dependent on one proprietary platform.

37. Registry and security

The registry may contain sensitive information.

Agent permissions schemas may reveal the security model, validation rules may reveal control mechanisms, examples may contain Operational DNA, and metadata names may reveal governance structure.

Implementations must distinguish public standard registry, internal implementation registry, and restricted operational registry.

Minimum requirement

Registry content must be classified according to what it reveals.

38. Registry and examples

Every important schema should have examples.

Examples may include minimal example, complete example, invalid example, AI-generated draft example, approved example, and redacted sensitive example.

Examples matter for people and AI.

Minimum requirement

High-risk schemas must include examples and anti-examples.

39. Registry and anti-patterns

AIFC rejects these anti-patterns.

39.1 Creative schema drift

Every agent creates a different artefact format.

39.2 Metadata overload

Artefacts have so many fields that people stop using the system.

39.3 Metadata theater

Fields exist, but no one uses them for decisions, validation, or work.

39.4 Missing owner

Schemas exist, but no one maintains them.

39.5 Schema without examples

A schema exists, but people and agents do not know how to use it.

39.6 Hidden schema in tool

Structure is locked inside a proprietary tool and cannot be exported.

39.7 Draft schema used as active

An agent uses an experimental schema as a stable rule.

39.8 Validation disconnected from schema

The validator checks something different from what the registry defines.

39.9 Classification ignored

Metadata and schemas reveal sensitive know-how without protection.

39.10 Sequential IDs as primary identity

Sequential numbers are used as primary identity and break when artefacts move.

39.11 No migration path

A schema change breaks the existing knowledge base.

39.12 Machine-only registry

The registry is so technical that people cannot understand it.

40. Minimal requirements

Schemas and Metadata Registry must at minimum:

1. Provide a catalogue of key artefacts and metadata.
2. Give critical repeatable artefacts stable structure.
3. Give critical artefacts metadata for ownership, status, classification, and review.
4. Distinguish the standard registry from community content.
5. Give every key schema human-readable purpose and use.
6. Include instructions or references for agentic use.
7. Provide software-verifiable parts for critical schemas where practical.
8. Have stable location and naming.
9. Define common metadata fields and their meaning.
10. Give critical artefacts stable identity independent of order.
11. Give critical artefacts explicit or inherited type.
12. Give critical artefacts status or inherited status.
13. Give critical artefacts owner or owning role.
14. Give critical artefacts classification or inherited classification.
15. Provide AI processing rule for restricted or Operational DNA artefacts.
16. Provide review rule or trigger for critical artefacts.
17. Require approval metadata for artefacts changing active governance or public commitments.
18. Provide lineage or evidence reference for critical AI-generated artefacts.
19. Make critical relationships between decisions, workflows, risks, agents, and skills traceable.
20. Define status values and transitions for artefacts with lifecycle.
21. Define or validate critical status transitions.
22. Distinguish required, recommended, and conditional fields.
23. Define conditional metadata rules for critical situations.
24. Make metadata inheritance explicit and override traceable.
25. Make override of critical metadata auditable.
26. Give critical schemas version and status.
27. Include migration guidance for breaking schema changes.
28. Give registry schemas lifecycle status.
29. Give registry owner and change governance.
30. Support human-readable forms and cockpit views where practical.
31. Require AI agents creating AIFC artefacts to follow the relevant schema or explain deviations.
32. Reference schema fields and standard requirements from validation rules.
33. Standardize compliance artefact structure.
34. Keep core schemas portable and not dependent on one proprietary platform.
35. Classify registry content according to what it reveals.
36. Include examples and anti-examples for high-risk schemas.

41. Summary

Schemas and Metadata Registry gives the AIFC knowledge base a shared shape.

Without the registry, every person, team, project, and agent would create different structures.

With the registry, the community can preserve consistency, validate artefacts, run AI agents, build a Human Cockpit Layer, and assess compliance without chaos.

AIFC states:

Structure knowledge enough for agents.
Keep it readable enough for humans.
Validate it enough for trust.

The registry is not bureaucracy. It is the shared grammar of community know-how.

Schemas and Metadata Registry turns AIFC knowledge into consistent, portable and agent-usable structure.