feat(schema): add models/tools/agents to drive schema updates

[ramizpolic]

Overview

Introduces a cleaner data model for OASF: a top-level Record carries
identity, and every payload hangs off it as a tree of typed modules
organised into three tiers — resource/, interface/, and
traits/. Six worked examples and a full DATA_MODELS.md rewrite ship
with the schema so the shape is easy to learn from real records.

Why

The previous module split (core/* + integration/*) made it difficult to answer:

1. What kind of thing is this module? — subject, exposed surface, or
   property? Nothing in the type string told you.
2. How to compose modules? — every module had its own composition rule,
   which was hard to remember and easy to misuse.

The new shape answers all three at a glance:

• Type prefix (resource/, interface/, traits/) tells you the role.
• Only two composition modes — instance (things you enumerate) and
  replace (properties, deepest wins).
• Record is a first-class top-level message; modules are strictly its
  payload.

The taxonomy at a glance

Record                              ← identity + skills/domains + modules[]
├── resource/model/language         ← subjects: models, skills, prompts
├── resource/skill/agentskill
├── resource/skill/prompt
├── interface/framework/mcp         ← exposed surfaces: MCP, A2A
├── interface/framework/a2a
└── traits/*                        ← properties (leaves, replace on nest)
    ├── traits/access/permissions
    ├── traits/quality/evaluation
    └── traits/runtime/requirements

Placement rules:

• resource/* and interface/* are subjects — they sit under the
  record root, and may nest traits/* scoped to them.
• traits/* are leaves — they never host children. Nesting a trait
  inside a subject narrows the scope; the inner trait replaces the outer
  one for that subtree.

actor/* — compound subjects such as actor/agent, actor/crew,
actor/workflow — are deliberately deferred to a follow-up PR. Actors
will be the only tier allowed to host resource/* and interface/* as
children (in addition to traits/*).

What changed in the repo

New: top-level types

• proto/agntcy/oasf/types/v2alpha1/record.proto — Record message with
  schema_version, name, version, description, created_at,
  authors, licenses, publisher, skills, domains, annotations,
  and modules[].
• proto/agntcy/oasf/types/v2alpha1/module.proto — recursive Module
  envelope (type, annotations, data, modules[]).

New: modules, versioned per family

Each module family has its own local v1alphaN — bumping one family does
not force any other to bump.

Type	Message	Proto
resource/model/language	Language	modules/resource/model/v1alpha1/language.proto
resource/skill/agentskill	AgentSkill	modules/resource/skill/v1alpha1/agentskill.proto
resource/skill/prompt	Prompt	modules/resource/skill/v1alpha1/prompt.proto
interface/framework/mcp	Mcp	modules/interface/framework/v1alpha1/mcp.proto
interface/framework/a2a	A2A	modules/interface/framework/v1alpha1/a2a.proto
traits/access/permissions	Permissions	modules/traits/access/v1alpha1/permissions.proto
traits/quality/evaluation	Evaluation	modules/traits/quality/v1alpha1/evaluation.proto
traits/runtime/requirements	Requirements	modules/traits/runtime/v1alpha1/requirements.proto

New: worked examples

Six real-world records under examples/:

• Models — local-models.json (Llama
  3.3 70B, Qwen 2.5 Coder 7B, Mistral 7B v0.3),
  openai.json (OpenAI o1).
• Tools — coverage.json (Codecov
  agent-skill), devops.json (docker, kubectl,
  terraform, github-actions, prometheus).
• Agents — mcp.json (Copilot MCP),
  ui-dev.json (Figma, Photoshop, React,
  Playwright).

Each demonstrates nested traits/* overriding record-level defaults, and
per-subject traits/quality/evaluation blocks.

Documentation

• DATA_MODELS.md rewritten end-to-end: overview, data
  tree, taxonomy, composition, catalog, authoring guide, versioning.

Out of scope (follow-up work)

• actor/* tier — actor/agent, actor/crew, actor/workflow and
  their selector grammar ($.children.<type>.<name>, $.steps.<id>).
• Server updates — server/** (Elixir) still contains lookups keyed
  on the old core/* type strings.
• JSON metaschema — schema/ still reflects the old catalog.

Examples

Follow-up PRs should enable the following structure

Single agent

Record  "org.example/web-researcher"
└── actor/agent  "web-researcher"
    ├── resource/model/language      "Llama 3.3 70B"
    ├── resource/skill/prompt        "system-prompt"
    │
    ├── resource/memory/vector       "short-term"   ← conversation window embeddings
    ├── resource/memory/episodic     "long-term"    ← past sessions, summaries
    ├── resource/knowledge/document  "docs-corpus"  ← RAG source (product docs)
    ├── resource/knowledge/graph     "entity-graph" ← named-entity graph
    ├── resource/tool/http           "web-search"   ← direct tool, not via MCP
    │
    ├── interface/framework/mcp      "web-researcher-mcp"
    │
    ├── traits/access/permissions    { network: read, docs-corpus: read }
    ├── traits/runtime/requirements  { binaries: [node>=18], network: [*] }
    └── traits/policy/guardrails     { pii_redaction: on, max_tokens: 8k }

MAS system

Record  "org.example/coding-team"
└── actor/crew  "coding-team"
    │
    ├── resource/memory/keyvalue     "crew-scratchpad"    ← shared crew state
    ├── resource/knowledge/document  "repo-docs"          ← shared knowledge
    │
    ├── actor/agent  "planner"                            ← speaks A2A
    │   ├── resource/model/language    "OpenAI o1"
    │   ├── resource/memory/episodic   "plan-history"
    │   └── interface/framework/a2a    "planner-a2a"
    │
    ├── actor/agent  "coder"                              ← exposes MCP
    │   ├── resource/model/language    "Qwen 2.5 Coder 7B"
    │   ├── resource/skill/agentskill  "code-writer"
    │   ├── resource/memory/vector     "code-context"     ← per-file embeddings
    │   ├── resource/knowledge/graph   "symbol-graph"     ← private to coder
    │   ├── resource/tool/shell        "git+build"
    │   ├── interface/framework/mcp    "coder-mcp"
    │   └── traits/runtime/requirements { binaries: [node>=18, git] }
    │
    ├── actor/agent  "reviewer"                           ← speaks A2A
    │   ├── resource/model/language    "Llama 3.3 70B"
    │   ├── resource/knowledge/document "style-guide"     ← private policy source
    │   └── interface/framework/a2a    "reviewer-a2a"
    │
    ├── traits/access/permissions   { repo: read_write, ci: read }   ← crew-wide default
    └── traits/policy/guardrails    { pii_redaction: on }             ← crew-wide default

[github-actions]

The latest Buf updates on your PR. Results from workflow Buf CI / buf (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	✅ passed	✅ passed	✅ passed	Jul 3, 2026, 12:55 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

This PR introduces a new OASF top-level Record envelope and a universal recursive Module envelope, alongside initial v1alpha1 module payload protos for resource/*, interface/*, and traits/*, plus worked JSON examples and a rewritten DATA_MODELS.md to document the new taxonomy and composition rules.

Changes:

• Added types/v2alpha1 protos for Record and the recursive Module envelope.
• Added initial module payload protos for resources (models/skills), interfaces (MCP/A2A), and traits (permissions/evaluation/requirements), plus shared objects (Artifact/EnvVar/HttpHeader).
• Added multiple worked example records under examples/ and rewrote DATA_MODELS.md to reflect the new data model.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
schema/objects/descriptor.json	Removes the legacy descriptor object from the JSON metaschema.
proto/agntcy/oasf/types/v2alpha1/record.proto	Defines the new top-level Record envelope for publications.
proto/agntcy/oasf/types/v2alpha1/module.proto	Defines the universal recursive Module envelope (type, data, modules).
proto/agntcy/oasf/objects/v1/http_header.proto	Adds reusable HttpHeader object for auth/metadata headers.
proto/agntcy/oasf/objects/v1/env_var.proto	Adds reusable EnvVar object for runtime environment variables.
proto/agntcy/oasf/objects/v1/artifact.proto	Adds reusable Artifact object for external payload references.
proto/agntcy/oasf/modules/traits/runtime/v1alpha1/requirements.proto	Adds traits/runtime/requirements trait payload.
proto/agntcy/oasf/modules/traits/quality/v1alpha1/evaluation.proto	Adds traits/quality/evaluation trait payload.
proto/agntcy/oasf/modules/traits/access/v1alpha1/permissions.proto	Adds traits/access/permissions trait payload.
proto/agntcy/oasf/modules/resource/skill/v1alpha1/prompt.proto	Adds resource/skill/prompt resource payload.
proto/agntcy/oasf/modules/resource/skill/v1alpha1/agentskill.proto	Adds resource/skill/agentskill resource payload.
proto/agntcy/oasf/modules/resource/model/v1alpha1/language.proto	Adds resource/model/language resource payload for LMs.
proto/agntcy/oasf/modules/interface/framework/v1alpha1/mcp.proto	Adds interface/framework/mcp interface payload for MCP servers.
proto/agntcy/oasf/modules/interface/framework/v1alpha1/a2a.proto	Adds interface/framework/a2a interface payload for A2A-exposed agents.
examples/tools/devops.json	Adds a worked example record for a DevOps agent-skill collection.
examples/tools/coverage.json	Adds a worked example record for a Codecov coverage skill.
examples/models/openai.json	Adds a worked example record for a hosted OpenAI model.
examples/models/local-models.json	Adds a worked example record for local/self-hosted models.
examples/agents/ui-dev.json	Adds a worked example record for a UI-dev MCP server collection.
examples/agents/mcp.json	Adds a worked example record for a GitHub Copilot MCP server.
DATA_MODELS.md	Full rewrite documenting the new Record/Module tree, taxonomy, and composition.
.vscode/settings.json	Adds an (empty) VS Code workspace settings file.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ramizpolic]

It is also possible to represent the core record object as a Module due to nesting and make Directory work with arbitrary modules as TLD objects, but this would require a fair amount of changes and can be tracked for v2 releases across OASF and DIR. For now, the suggested changes can go into v1.X or v2.0-alpha

[ramizpolic]

Added a schema builder PoC to make it easier to understand how to compose a record, but also understand the meaning and ideas behind the spec A record defines an agentic resource of...

The UI can be viewed locally with task ui:builder

Concerns/Notes

The current module taxonomy needs to be slightly patched (the Resource category is strange/hard to define, alternatively use Tools instead). Agents and models as TLD module taxonomy makes sense, but for things like prompts and agent skills, not sure what the ideal TLD taxonomy would be.

[akijakya]

I like the overall direction, including dropping the original Record object and compose records only with modules.

[akijakya]

I think deleting this is a bit premature, also breaks the CI

[akijakya]

I really like that we can have an UI like this, it should be added properly to the OASF UI (integrate it with the Phoenix framework in Elixir)!

[akijakya]

With this many fields in the A2A and MCP protos, aren't we slipping into maintaining other project's schemas? Shouldn't only fields that have value in record/module discovery be added?

[akijakya]

Shouldn't artifact be a module-level field?