This guide explains how to register new entries in CMIP7 Controlled Vocabularies (CVs) such as institutions, models (source_id), experiments, and model documentation components.

1. Overview¶

CMIP7 uses Controlled Vocabularies (CVs) to ensure consistency across all participating modelling centres. Before publishing data, you must register:

• Your institution
• Your model (source_id)
• Any new experiments (if applicable, to be done by MIP leads)
• Model documentation (EMD) components

Registration is done through GitHub issue forms that are linked below (no Git expertise required).

2. Registration Forms¶

2.1 Institution Registration¶

Register your institution before registering a model. This requires the creation of two "objects"; the institution member id and the institution id.

In CMIP6 several institution ids represented a collection of multiple institutes (see for example E3SM-Project and EC-Earth-Consortium within the CMIP6 CVs). For CMIP7 this would be achieved through multiple institution member registrations and a single institution id registration. The institution id is then used in data preparation and publication processes.

If there is only a single institution member publishing under a single institution id then it is necessary to complete both registration forms, but only a single institution member needs to be referenced in the second form.

The complete the institution registration it is necessary to

1. register as an 'institution member' with an associated ID (i.e. DRS name)
2. register for an institution ID (i.e. DRS name) based on the members that should be associated with the institution ID
   • If your institution ID is associated with a consortium, you will have more than one member and an institution ID that differs from those of your members
   • If your institution ID is associated with a single member, you will have one member and an institution ID that is the same as the the member's ID (i.e. DRS name).

Repository: CMIP7-CVs Registered content for institutes, Registered content for institute members

Notes: - The acronym used for the institution id must be unique and cannot be changed once data is published - An ROR (Research Organisation Registry) identifier is required for traceability. Find yours at ror.org - If you previously did the institution ID registration process, but your institution is not in the CVs, please raise an issue in the CMIP7-CVs repository

2.2 Model Registration (source_id)¶

Important: To register a source_id, you must complete the EMD (Essential Model Documentation) registration process.

Guidance on constructing a source id is provided in the Source ID Guidance

Prerequisites: 1. EMD registration completed (see 2.4) - including grids, components, and top-level Model

Repository: CMIP7-CVs Registered Content (content populated via the EMD)

Grid labels and Source IDs will be registered automatically within the CVs once the relevant EMD stages have been completed. If you have completed the EMD but your source ID or grid label is not in the CVs, please open an issue in the CMIP7 CVs repository so we can figure out where the information processing has gone wrong.

2.3 Activity Registration¶

For new Activities (MIPs) not already in the CV. If you previously did the activity registration process, but your activity is not in the CV, please check and engage on this issue which tracks the progress and process for adding these lost registrations back into the CV.

Repository: CMIP7-CVs Registered Content

2.4 Experiment Registration¶

For new experiments not already in the CV. If you previously did the experiment registration process, but your experiment is not in the CV, please check and engage on this issue which tracks the progress and process for adding these lost registrations back into the CV.

Repository: CMIP7-CVs Registered Content

2.5 Essential Model Documentation (EMD)¶

EMD provides detailed technical documentation of your model. Registration follows a hierarchical process - you must register components in order. This should take a maximum of 4 hours wall time (although not all at once, as each step has a separate review process).

For information on the EMD please read the DOCUMENTATION

Other links: GitHub Repository

Registration Order¶

flowchart LR
    A["1. Grid Cells"] --> B["2. Computational Grids (Horizontal + Vertical)"]
    B --> C["3. Model Components (atmosphere, ocean, etc.)"]
    C --> D["4. Top-level Model"]

Available Forms¶

3. Registration Workflow¶

Overall Registration Order¶

flowchart LR
    A["1. Institution (CMIP7-CVs)"] --> B["2. EMD Registration (Essential-Model-Documentation)"]
    B --> C["3. source_id (CMIP7-CVs, automated)"]
    C --> D["4. Experiments (if needed, MIPs to request via CMIP7-CVs)"]

Step-by-Step Process¶

1. Check if already registered: Before creating a new entry, verify it doesn't already exist (see links above for how to check)
2. Fill the form: Click the appropriate link and complete all required fields
3. Submit: This creates a GitHub issue
4. Automated checks: The system performs initial validation
5. Review: A reviewer checks your submission
6. Feedback loop: You may be asked to make corrections
7. Approval: Once approved, the entry is merged into the relevant repository

Typical Timeline¶

• Simple registrations (institution, component configuration): 1-3 days
• Complex registrations (grid-cells, source-id): May take longer due to dependencies and clarifications

Tips¶

• Don't wait: Start EMD registration early - dependencies mean sequential steps
• Check dependencies: A Model Component cannot reference a grid that isn't registered yet, a source cannot refer to components that don't exist.
• Be precise: Acronyms and identifiers cannot be changed after data publication
• Ask for help: Consult the documentation first, and if needed use the general forms linked below for questions.

4. After Registration¶

Once your entries are registered:

1. The esgvoc library will include your entries in the next update
2. Your registered identifiers will appear as valid entries in the CMIP7 CMOR tables
3. Your model output netCDF files will be able to pass QA/QC validation for these CV fields

5. Tools & Resources¶

esgvoc Library¶

The esgvoc Python library provides programmatic access to all CVs:

• GitHub: https://github.com/WCRP-CMIP/esgf-vocab
• Documentation: https://esgf.github.io/esgf-vocab/
• Accessing the CMIP7 CVs via esgvoc documentation: https://github.com/WCRP-CMIP/CMIP7-CVs#viewing-the-cvs-and-browsing-terms

CV Repositories¶

EMD Repositories¶

These repositories maintain the information used by the EMD. Some of the information is automatically translated out into the CV repositories, but these EMD repositories are not themselves CV repositories. Your data is only registered in the CVs if it appears in the CVs repositories above. Registration in the EMD repositories alone is not registration in the CVs. However the EMD information required by the CVs should automatically propagate into the CVs on successful completion of the relevant EMD stages.

6. Getting Help¶

• Question about a specific CV value: Open a CV value issue in the CMIP7 CVS repository
• CV discussions: See Discussions on the CVs repo
• General questions: Open a blank issue in the CMIP7 CVS repository and ask your question. Please include as much context and other helpful information as possible.
• Contact IPO: For complex or sensitive cases, contact the CMIP International Project Office