In research, if our methodology is not transparent, our results are not verifiable. Using AI to help generate code or synthesize data is dramatically affecting transparency, sustainability and maintenance. But how can we make the AI involvement more transparent and traceable?

Provenance in the age of AI: Why we need AI Declarations for more transparency This image was generated using Google Gemini 3.1. See the declaration file at the end of this blog post for more details.Before I started as a Research Software Engineer, I worked in a physical lab where the culture of provenance was absolute. You documented everything: the materials, the hardware, the exact version of the software you used to process the data, and so forth. Without that trail, the results were meaningless. You could not trust them, and you certainly could not reproduce them.

Today, my “lab” is entirely digital, but the need for that same precision remains.

Over the last two years, a new variable has entered our work. We are using Generative AI to suggest code refactors, autonomous agents to synthesize datasets, and generative models to draft technical reports. AI is no longer a separate tool we are experimenting with; it is already becoming a standard part of our daily routine.

Today, when I download a dataset or review a colleague’s pull request, I have no way to know where the human logic ends and the model’s output begins. This ambiguity is a problem for scientific reliability. If we cannot trace the logic of an algorithm or the origin of a dataset, we lose reproducibility. If we cannot identify which parts of a codebase were generated by a model, we are building up a “maintenance debt” that will eventually come due. And if we ignore the compute cost of these models, we are ignoring the sustainability of our field.

We built the AI Declaration Format**** (https://ai-declaration.org)** to address this. Our goal is to make structured documentation of AI usage a standard, routine part of professional work.

The foundation: A machine-readable file format

The AI Declaration Format is the foundation: a machine-readable, general-purpose file format designed to describe AI involvement in any digital artifact. It does not matter if you are publishing software, a research paper, a dataset, or media; you can use the same structured approach to say how AI was involved.

We designed the schema to be modular, so you can focus on the parts that matter for your project:

  • Maintainability and Security: You can track which modules were AI-assisted and document security reviews. Knowing which blocks of code were generated helps future maintainers understand the intent behind them.
  • Environmental Impact: You can record compute hours and estimated carbon footprints. This turns “sustainability” into a measurable metric.
  • Explainability and Governance: For systems that interact with users, you can document technical decision logic or interpretability methods. You can also name responsible officers and link to internal ethics reviews.
  • Regulations (not just the EU Act): With the EU AI Act, the US Executive Order, and other global frameworks, transparency is becoming a legal requirement. The AI Declaration Format lets you map your project to risk categories and link to the technical documentation these laws demand.

Why another format?

A common question is why we need a new format when standards like SPDX 3.0 (AI Profile) and CycloneDX (ML-BOM) already exist. The answer lies in the scope and the audience:

  • SPDX and CycloneDX are “Bill of Materials” (SBoM) standards. They are designed for legal teams and security auditors to track every sub-component and vulnerability in a supply chain. They are powerful but often complex for an individual researcher or a small dev team.
  • CodeMeta and CITATION.cff are useful for general project metadata and academic citations. However, they lack the specialized fields needed for AI transparency — such as risk classification, model versions, and human oversight.
  • The AI Declaration Format is a declaration format, not a full inventory. It is designed to be human-writable and project-focused. It answers the specific question of “How did the humans on this project use AI?”.

The AI Declaration Format sits alongside these standards: it is the missing piece of the metadata puzzle that captures the usage and methodology of Generative AI.

How do I get started?

A standard is only useful if it is easy to adopt. We have built an ecosystem of tools and automation around the AI Declaration Format to ensure it fits into your existing workflow. We are also working on improving and extending this tooling, including GitHub/GitLab Actions and workflows to automate validation and updating as part of your CI/CD pipelines:

  • The Web App**: If you want a guided interface, we built a web app specifically to create these declaration files. It runs entirely in your browser, so your project data never hits our servers. You can generate an aidecl.yaml, validate it, or look at examples from other fields.
  • The CLI: For those of us who live in the terminal, the aidecl tool lets you initialize and validate declarations as part of your git workflow. It runs semantic checks to make sure your claims actually make sense—like flagging if you claim no AI was used but then list three models in your inventory.

Scientific and Technical Standards

In research, we document our hardware and our data sources because that is how we maintain the standard of our work. This is the bedrock of Open Science: if our methodology is not transparent, our results are not verifiable. Using AI to help generate code or synthesize data is simply another part of that methodology. It belongs in the formal record.

Adding an aidecl.yaml to your repository shows a commitment to open science principles. It is a way to make sure that the things we are building today will be MORE understandable, maintainable, and reproducible in future.

Join the effort

We are in the early stages of this, and we need a community to make it a standard.

  • Adopt: Add an aidecl.yaml to your next project. It takes about five minutes.
  • Endorse: If your lab or organization values AI transparency, we need early adopters to help build credibility.
  • Contribute: The schema and tools are open-source. Help us improve the validation rules or the web interface.
  • Feedback: We need to know how this works (or does not) for your specific field — whether that is genomics, legal tech, or creative media.

We are all figuring this out as we go. As the technology changes and we get more feedback, the file format and the tools will evolve to keep up.

AI Declaration (aidecl.yaml) for this post

schema_version: “1.0.0” project: name: “Provenance in the age of LLMs: Why we need AI Declarations” version: “1.0.0” content_type: “document” license: “CC BY 4.0” ai_usage: used: true summary: “Structured and refined by Gemini (LLM) based on human-provided themes, constraints, and source documentation.” level: “moderate” activities: - content_drafting - content_editing tools: - name: “Gemini” vendor: “Google” type: “assistant” model: “gemini-3.1” purpose: - content_refining - structural_organization - image_generation ai_proportion: qualitative: mostly_human method: self_reported governance: responsible_officer: “Faruk Diblen” ethics_review_status: “not_applicable” environmental: compute_hours: 0.05 estimation_method: self_estimated security: review_performed: true review_type: - human_in_the_loop declaration: date: “2026-04-07” declared_by: “Faruk Diblen” organization: “Resoft Labs”

Acknowledgements

Thanks to [Flavio Hafner], [Carlos Martinez-Ortiz] and [Elena Ranguelova] for their feedback on the text and [Pablo Rodríguez-Sánchez] and [Alexander Hadjiivanov] for their editorial support.