AI Declaration Format Schema (aidecl)

A JSON Schema and JSON-LD context for machine-readable AI usage declarations in digital work.

AI Declaration files (aidecl.yaml or aidecl.json) describe how AI tools were used in the creation of software, datasets, documents, models, media, and other digital artifacts. They provide transparency about AI involvement for compliance, governance, and trust.

Architecture Overview

The AI Declaration Format ecosystem is split across four repositories:

• aidecl-schema (this repo): JSON Schema definition, JSON-LD context for linked data, and example declaration files. This is the foundation.
• aidecl-cli: Python CLI tool for validating declaration files against the schema. Bundles a copy of schema.json as package data.
• aidecl-web: Web application for creating and validating declarations through a browser interface. Derives TypeScript types from the schema.
• aidecl-landing: Static site explaining the format and encouraging adoption.

Schema

The schema uses JSON Schema Draft 2020-12 and is defined in schema.json.

Schema identifier: https://ai-declaration.github.io/schema/v1/aidecl.schema.json

Declaration Files

Declaration files can be written in either YAML or JSON:

• aidecl.yaml: recommended for human-authored declarations (more readable, supports comments)
• aidecl.json: recommended for machine-generated declarations or when JSON-LD context is needed

Both formats follow the same schema structure.

JSON-LD Context

The file context.jsonld provides linked data mappings so that AI Declaration files can be consumed as RDF. It maps fields to established vocabularies:

• Schema.org: common properties (name, version, description)
• PROV-O: provenance (attribution, generation timestamps)
• FOAF: people (declared_by maps to foaf:Person)
• Dublin Core: metadata (title, date)
• SPDX: license identifiers

Context URL: https://ai-declaration.github.io/schema/v1/context.jsonld

Examples

Example	Formats	Description
minimal	yaml, json	Smallest valid declaration (no AI used)
no-ai-used	yaml, json	Explicit no-AI declaration with project context
basic-with-ai	yaml, json	Light AI usage with one tool
late-stage-ai	yaml, json	AI introduced only in final development phase
comprehensive	yaml, json	All schema fields populated

Schema Fields

Required fields

Field	Type	Description
schema_version	string	Semver version of the schema (e.g. "1.0.0")
project	object	The work being declared (name required)
ai_usage	object	AI involvement details (used required)
declaration	object	Attestation metadata (date, declared_by required)

Optional top-level sections

Section	Description
risk_management	Risk mapping, measurement benchmarks, mitigation
explainability	Decision logic, user-facing explanation
compliance_eu_ai_act	EU AI Act classification and regulatory fields
governance	Responsible officer, ethics review status
data_handling	Data classification, DPIA, DPA status
environmental	Compute hours, energy, carbon footprint
security	Review status, dependency verification
compliance	Organizational policy and frameworks

Activities

The activities field is a string array listing what AI helped with. Instead of the software-specific boolean flags in scope, this works across all content types. Values can be predefined vocabulary or free-text.

Suggested vocabulary by content type:

Content type	Suggested activities
software	code_generation, code_completion, code_review, documentation, testing, debugging, infrastructure, refactoring
dataset	data_collection, data_cleaning, data_labeling, data_augmentation, data_analysis
document	content_drafting, content_editing, content_summarization, translation
model	model_training, model_evaluation, hyperparameter_tuning, feature_engineering, architecture_search
media	image_generation, video_generation, audio_generation, media_editing, media_enhancement

These values are not enforced by the schema; any non-empty string is accepted.

AI Proportion

The ai_proportion field allows qualitative labels as an alternative (or addition) to exact percentages:

Label	Meaning
entirely_human	No AI involvement
mostly_human	AI used minimally, humans did most work
mixed	Roughly equal AI and human contribution
mostly_ai	AI did most of the work, humans reviewed/edited
entirely_ai	Fully AI-generated

You can use qualitative only, percentages only, or both:

# Qualitative only (most users)
ai_proportion:
  qualitative: mostly_human

# Percentages only
ai_proportion:
  ai_generated_percent: 30
  ai_assisted_percent: 40
  human_only_percent: 30
  method: tool_measured

# Both (label as summary, numbers as detail)
ai_proportion:
  qualitative: mixed
  ai_generated_percent: 30
  ai_assisted_percent: 40
  human_only_percent: 30

The older scope and code_proportion fields remain available for backward compatibility.

Conditional Rules

The schema enforces the following conditional requirements:

1. When ai_usage.used is true, the field ai_usage.summary becomes required. Declarations that claim AI was used must explain how.

2. When compliance_eu_ai_act.classification is "high_risk", the following fields become required:

   • technical_documentation_url
   • declaration_of_conformity_url
   • human_oversight

3. Advisory: When data_handling.data_classification is "confidential" or "restricted", conducting a DPIA (dpia.conducted: true) is recommended but not enforced by the schema.

Privacy Considerations

Declaration files may be committed to public repositories. Consider the following:

• The declared_by field identifies who made the declaration. For public repos, consider using team names or roles (e.g. "Development Team") rather than individual names.
• Review whether any fields contain information that could identify individuals.
• Be aware of GDPR right-to-erasure implications if personal names are used in public declarations.

Versioning Policy

The current schema version is 1.0.0.

Versioning follows semantic versioning:

• Patch (1.0.x): Bug fixes to descriptions or patterns
• Minor (1.x.0): New optional fields (backward-compatible)
• Major (x.0.0): Breaking changes to required fields or structure

The schema_version field in declaration files indicates which version they target. Validators should check compatibility between the declared version and the schema version they support.

Compatibility Matrix

Tool	Supported schema versions
aidecl-cli 0.1.x	1.0.0
aidecl-web 0.1.x	1.0.0

EU AI Act Coverage

The compliance_eu_ai_act section maps to specific EU AI Act provisions:

Schema field	EU AI Act reference
classification	Article 6 (risk categories)
ai_generated_content_disclosure	Article 50(1)
deepfake_disclosure	Article 50(4)
technical_documentation_url	Annex IV
human_oversight	Article 14
conformity_assessment_body	Article 43
ce_marking_applied	Article 49
fundamental_rights_impact_assessment	Article 27
post_market_monitoring_plan	Article 72
serious_incident_reporting	Article 73
gpai_model_provider, gpai_systemic_risk	Chapter V (Articles 51-56)
training_data_summary_url	Article 53

Quick Start

Minimal YAML declaration:

schema_version: "1.0.0"
project:
  name: my-project
ai_usage:
  used: false
declaration:
  date: "2025-01-01"
  declared_by: Development Team

Badge

Add to your README to indicate your project includes an AI declaration:

![validated with aidecl](https://img.shields.io/badge/ai%20declaration%20format-aidecl-blue)

Related Repositories

• cli: command-line validator
• web: web-based generator and validator
• landing: project landing page

Known Limitations

• No multi-language support for description or purpose fields (planned for future versions)
• No SHACL or ShEx shapes for RDF validation (future work)
• JSON Schema cannot enforce that percentages in code_proportion or ai_proportion sum to 100. This is a semantic check handled by the CLI validator.
• No field deprecation mechanism yet
• additionalProperties is not set to false, which means unknown fields pass schema validation. This is intentional for extensibility. Strict validation modes in tooling may optionally reject unknown properties.

License

This work is licensed under CC BY-SA 4.0.

The schema, JSON-LD context, and example files are data/specification artifacts. If you bundle the schema in your tools or services, attribution is required and derivative works must use the same license. See LICENSE for the full text.