agents-json 1.0.0

agents.json Check v1.0.0

Status

• Version: 1.0.0
• Check identifier: agents-json
• Input contract: [email protected]
• Output contract: [email protected]
• Scope: site

Abstract

This check validates Wildcard-style agents.json discovery for OpenAPI-based agent workflow contracts. It does not validate the older lightweight directory shape that only lists name and url, and it does not validate A2A Agent Cards.

Motivation

Wildcard agents.json is an emerging OpenAPI-adjacent proposal for describing API actions, flows, links, examples, and authentication context so agents can reason about workflows. A scanner can validate that the public contract is structurally useful without executing workflows or treating the proposal as an IETF, IANA, W3C, OpenAPI Initiative, or A2A standard.

Normative Model

The preferred discovery path is:

• /.well-known/agents.json

The accepted fallback path is:

• /agents.json

The expected document is a JSON object that resembles a Wildcard agents.json contract:

• version or schema information when available.
• site/API information.
• OpenAPI reference or OpenAPI-like operations.
• actions or operations.
• flows.
• links.
• examples.
• auth/security declarations.

Applicability

The check applies to public site origins. Absence is a warning by default because agents.json is an emerging readiness signal. A malformed published file fails because the site attempted the convention but produced unusable metadata.

Pass Criteria

The check passes when:

• a candidate resource is found at the preferred path or accepted fallback.
• the response body parses as a JSON object.
• the document matches the Wildcard-style schema shape.
• the document declares or implies a supported version.
• API/action definitions are present and structurally valid.
• flows are present and non-empty.
• each flow references existing actions or operations.
• links, when present, reference existing source and target actions or operations.
• examples, when present, are parseable and attached to valid actions or flows.
• parameter schemas are JSON Schema or OpenAPI-compatible objects.
• auth/security declarations are structurally valid.
• URLs are valid relative or HTTP(S) URLs.
• no public credentials or secret-bearing URLs are present.

Warning Criteria

The check warns when:

• /.well-known/agents.json is absent.
• only /agents.json fallback is found.
• JSON is parseable but served with a generic or incorrect content type.
• the file matches the old lightweight directory shape instead of Wildcard shape.
• schema/version information is missing but the document otherwise resembles Wildcard shape.
• schema/version information is newer than the check supports.
• flows are too thin to guide execution.
• actions have weak descriptions.
• examples are absent for complex actions.
• parameters lack descriptions or examples.
• links do not explain data mapping clearly.
• remote OpenAPI or schema references are cross-origin.
• auth/security declarations are present but incomplete.
• OAuth is referenced without enough issuer, authorization server, or scope information.
• roadmap-style features such as loops, conditionals, pagination, streaming, or failure handling are referenced without stable schema support.
• workflow execution would require side effects, credentials, or payment.

Failure Criteria

The check fails when:

• a published candidate is not parseable JSON.
• the root document is not an object.
• the document does not match the Wildcard-style schema shape.
• required version/schema fields are malformed when present.
• API/action definitions are missing.
• flows are missing when the document claims executable workflows.
• flows reference missing actions or operations.
• links reference missing source or target operations.
• parameter schemas are malformed.
• examples are malformed or incompatible with declared schemas.
• URLs are invalid.
• auth/security declarations are malformed.
• public credentials, API keys, Bearer tokens, passwords, or secret-bearing URLs appear in public fields.

Evidence Model

Evidence includes:

• candidate paths attempted.
• selected resource URL.
• preferred or fallback path classification.
• HTTP status and content type.
• cache headers.
• parse result.
• detected schema/version.
• schema-shape classification.
• API/action count.
• flow count.
• invalid flow summaries.
• link count.
• invalid link summaries.
• example count.
• parameter schema validation summary.
• auth/security summary.
• remote reference list.
• public-secret scan summary.
• roadmap-feature indicators.

Validation And Scoring Steps

• discover-agents-json (0.20): discover preferred and fallback agents.json paths.
• validate-schema-shape (0.20): validate Wildcard-style schema shape.
• validate-actions (0.20): validate API actions or OpenAPI operations.
• validate-flows-links (0.20): validate flows and links without executing them.
• examples-usability (0.10): review examples and LLM argument-generation usability.
• security-hygiene (0.10): review public-contract security hygiene.

Standard Behavior

Wildcard agents.json proposes /.well-known/agents.json as a public workflow contract for agent-facing API execution. It builds on OpenAPI and adds workflow-level context such as flows, links, and examples.

Non-Standard And Real-World Behavior

Wildcard agents.json is an open proposal, not an IETF/IANA/W3C/OpenAPI Initiative/A2A standard. The check treats /agents.json as fallback evidence and labels old directory-only files as non-conformant to this check version.

Non-Goals And Limitations

• Does not validate A2A Agent Cards.
• Does not validate MCP Server Cards.
• Does not execute workflows by default.
• Does not send credentials.
• Does not treat Wildcard agents.json as a standards-body specification.
• Does not pass old name plus url directory files as Wildcard conformance.
• Does not depend on the OpenAPI discovery check result.

References

• github.com/wild-card-ai/agents-json
• github.com/wild-card-ai/agents-json/blob/master/agents_json/agentsJson.schema.json
• github.com/wild-card-ai/agents-json/tree/master/agents_json
• wild-card.ai/registry
• spec.openapis.org/oas/latest.html
• json-schema.org/specification
• www.rfc-editor.org/rfc/rfc8615

agents-json v1.0.0 Changelog

Initial Wildcard-style agents.json check.

• Validates /.well-known/agents.json as the preferred discovery path.
• Treats /agents.json as fallback evidence.
• Checks OpenAPI-adjacent actions, flows, links, examples, schema shape, and public-contract security hygiene.
• Rejects old directory-only name plus url files as Wildcard conformance.
• Does not execute workflows or depend on the OpenAPI discovery check result.