Directory server rejects real taxonomy skill names; only bare numeric id works · Issue #1943 · agntcy/dir · GitHub
Skip to content

Directory server rejects real taxonomy skill names; only bare numeric id works #1943

Closed as not planned
ruvnet/metaharness
#157
Closed as not planned
Directory server rejects real taxonomy skill names; only bare numeric id works#1943
ruvnet/metaharness
#157

Description

@ruvnet
ruvnet
opened on Jul 31, 2026

What happened

Pushing a record with a skills[] entry that includes a name field fails validation, even when name is the taxonomy's own real, current dotted path (e.g. software_engineering/code_generation/code_generation, pulled directly from this repo's schema/skills/software_engineering/code_generation/code_generation.json, which has "uid": 1 under category software_engineering ("uid": 6)).

Sending the same skill with id only, no name field at all, succeeds.

Reproduction

Using agntcy-dir (npm, v1.5.0) against a local Directory server (built from this repo's install/docker/docker-compose.yml, DIRECTORY_SERVER_AUTHN_ENABLED=false):

import { Client, Config } from 'agntcy-dir';

const config = new Config('localhost:8888');
const transport = await Client.createGRPCTransport(config);
const client = new Client(config, transport);

const baseRecord = {
  name: 'repro-record',
  version: '0.0.1',
  schema_version: '0.8.0',
  description: 'repro',
  authors: ['repro'],
  created_at: new Date().toISOString(),
  locators: [],
  domains: [],
  annotations: {},
  modules: [],
};

// FAILS — every name format tried:
await client.push([{ data: { ...baseRecord, skills: [{ id: 60101, name: 'software_engineering/code_generation/code_generation' }] } }]);
// -> invalid_argument: record validation failed: [ERROR: Unknown "name" value; no class is defined for code_generation. Attribute path: skills[0].]

await client.push([{ data: { ...baseRecord, skills: [{ id: 60101, name: 'code_generation' }] } }]);
// -> same error

await client.push([{ data: { ...baseRecord, skills: [{ name: 'software_engineering' }] } }]);
// -> Unknown "name" value; no class is defined for software_engineering.

// SUCCEEDS:
await client.push([{ data: { ...baseRecord, skills: [{ id: 60101 }] } }]);
// -> real RecordRef returned, record is real and lookup-able afterward

What I'd expect

Either:

  • name should accept the taxonomy's real dotted path (matching what's actually published in schema/skills/**), or
  • if id-only is the intended/correct usage today, it'd help a lot to say so explicitly somewhere discoverable (the agntcy-dir npm SDK's own examples/example.js sends both id and name together for its skills, e.g. { name: "natural_language_processing/natural_language_generation/text_completion", id: 10201 } — which looks like it would hit this same failure against the current schema, since those exact category/subcategory names (natural_language_processing, natural_language_generation) no longer exist in the current taxonomy (renamed to language_processing / language_generation at some point) — so that example may itself be stale.

Environment

  • agntcy-dir npm package: v1.5.0
  • Directory server: built from this repo's main branch (commit at time of testing), via install/docker/docker-compose.yml
  • Schema validation via DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL (default, https://schema.oasf.outshift.com)

Why I'm filing here

I dug into agntcy/oasf-sdk's Go client first, hoping to find (and possibly fix) the actual class-name lookup logic — but that package is just an HTTP client that POSTs to the configured schema URL; the actual validation logic isn't in any AGNTCY repo I could find, so a PR isn't something I'm able to put together. Filing this as a report instead, with what I hope is a tight enough repro to make it a quick fix (or a quick "here's the documented right way to do it" if I'm just missing something).

Happy to test a fix or a documentation clarification, whichever's easier on your end. Thanks for the great SDK otherwise — the rest of the push/publish/lookup flow worked cleanly on the first real try once this was worked around.

Activity

  1. github-project-automation
    added this to Discoveryon Jul 31, 2026
  2. github-project-automation
    moved this to Backlog in Discoveryon Jul 31, 2026
  3. ruvnet
    added 3 commits that reference this issue on Jul 31, 2026

    docs(agntcy): link the filed upstream issue (agntcy/dir#1943)

    d947775

    docs(adr): ADR-240 update section + finish the ADR-324->380 cross-ref…

    1a9e6ab

    ADR-240: AGNTCY identity, OASF export, observability, CASA compiler (#…

    7a57708

  4. ruvnet commented on Jul 31, 2026

    @ruvnet
    ruvnet
    on Jul 31, 2026
    Author

    Update: the id-only path is also inconsistent, not just name

    Following up with a broader finding while building out a full taxonomy-mapping table for a downstream integration.

    I generated the complete real skill leaf table from a fresh checkout of agntcy/oasf's schema/skills/** (364 leaves, composite id = category_uid*10000 + subcategory_uid*100 + leaf_uid, computed directly from each JSON file's own uid/extends fields — not guessed). I then live-pushed a spread of these correctly-derived ids against a local Directory server (same setup as the original report: agntcy/dir's own install/docker/docker-compose.yml, AUTHN_ENABLED=false), sending { id } only per the workaround above.

    Result: only id=60101 (software_engineering/code_generation/text_to_code) is accepted. Every other id tried — including ones for well-established subcategories — is rejected with the same no class is defined for <id> error as the name-based failures in the original report:

    id=60101:  OK
id=60501:  FAIL — no class is defined for 60501   (software_engineering/software_testing/unit_integration_testing)
id=60701:  FAIL — no class is defined for 60701   (software_engineering/code_quality/code_review)
id=100101: FAIL — no class is defined for 100101  (cybersecurity/application_security/secure_coding)
id=70906:  FAIL — no class is defined for 70906   (ai_ml_engineering/agent_orchestration/agentic_workflow_orchestration)
id=90502:  FAIL — no class is defined for 90502   (devops_cloud_infra/deployment_release/release_management)
id=60704:  FAIL — no class is defined for 60704   (software_engineering/code_quality/code_migration)
id=70904:  FAIL — no class is defined for 70904   (ai_ml_engineering/agent_orchestration/multi_agent_planning)
id=71003:  FAIL — no class is defined for 71003   (ai_ml_engineering/model_evaluation/llm_judge_evaluation)

    This is reproducible across a full docker restart of the apiserver container (ruled out local caching as the cause). Since the container delegates schema validation to DIRECTORY_SERVER_OASF_API_VALIDATION_SCHEMA_URL (default https://schema.oasf.outshift.com), this looks like the remote validation service's registered class set doesn't correspond to the current public agntcy/oasf main branch tree at all — id=60101 passing while every structurally-equivalent sibling id fails suggests either a very different/older pinned schema version behind that endpoint, or a near-empty/inconsistent class registry there.

    Happy to share the generator script (scripts/generate-oasf-taxonomy.mjs, walks the real schema tree, no manual data entry) if useful for reproducing against other id ranges. Not attempting a PR here for the same reason as the original report — the actual validation logic lives behind the remote schema.oasf.outshift.com service, not in a repo I can patch.

  5. ruvnet
    added a commit that references this issue on Jul 31, 2026

    feat(agntcy): real OASF taxonomy mapping + real TLS/x509/JWT auth wir…

    9f6d7e5

  6. akijakya commented on Jul 31, 2026

    @akijakya
    akijakya
    on Jul 31, 2026
    Member

    Hi! It seems like the problem is OASF version mismatch. The base record you test with has schema_version: '0.8.0',, but you are testing with skills from OASF version 1.1.0. The reason id 60101 (without name) works is that there is a skill with that id in OASF 0.8.0, and both id and name are valid identifiers by themselves, but if you provide mismatching id and name, that also results in an error.

  7. akijakya commented on Jul 31, 2026

    @akijakya
    akijakya
    on Jul 31, 2026
    Member
    // FAILS — every name format tried:
await client.push([{ data: { ...baseRecord, skills: [{ id: 60101, name: 'software_engineering/code_generation/code_generation' }] } }]);
// -> invalid_argument: record validation failed: [ERROR: Unknown "name" value; no class is defined for code_generation. Attribute path: skills[0].]

await client.push([{ data: { ...baseRecord, skills: [{ id: 60101, name: 'code_generation' }] } }]);
// -> same error

await client.push([{ data: { ...baseRecord, skills: [{ name: 'software_engineering' }] } }]);
// -> Unknown "name" value; no class is defined for software_engineering.

    Even with OASF 1.1.0, these tests will still fail because the correct name for this skill is software_engineering/code_generation/text_to_code. Please use the OASF API or the OASF-SDK with the official OASF instance URL to fetch the correct taxonomy.

  8. ruvnet commented on Jul 31, 2026

    @ruvnet
    ruvnet
    on Jul 31, 2026
    Author

    Resolved — this was our bug, not yours. Thank you!

    @akijakya nailed it exactly. Confirmed live: the record I was pushing declared schema_version: '0.8.0' while taxonomy.generated.json (and every id/name I tested) was generated from OASF 1.1.0's schema/skills/** tree. id=60101 only ever "worked" by coincidence — it happens to also be a real skill ("indexing") in 0.8.0, at the same numeric slot, completely unrelated to what I meant to send.

    Fixed schema_version to '1.1.0' and re-ran the exact same spot-check from my last comment — all 9 previously-"broken" ids now push successfully:

    id=60101, 60501, 60701, 100101, 70906, 90502, 60704, 70904, 71003 → all OK

    Also confirmed sending id and the taxonomy's own dotted name together (e.g. { id: 60101, name: 'software_engineering/code_generation/text_to_code' }) now works too — so the self-documenting form is fine, not just id-only. Updated my integration to send both.

    Apologies for the noise across two comments — this was entirely a stale-version bug on my side, not a validator inconsistency. Thanks for taking the time to dig in and explain the actual mechanism so clearly. Closing this out.

  9. ruvnet
    closed this as not plannedon Jul 31, 2026
  10. github-project-automation
    moved this from Backlog to Done in Discoveryon Jul 31, 2026
  11. ruvnet
    added a commit that references this issue on Jul 31, 2026

    fix(agntcy): schema_version mismatch was the real root cause, not a v…

    cd3242b
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions