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 (organisation)
• Your model (source_id)
• Any new experiments (if applicable)
• 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.

PROCESS UNDER REVIEW

Repository: WCRP-constants

Notes: - The acronym used for the institution id must be unique and cannot be changed once data is published - A ROR (Research Organisation Registry) identifier is required for traceability. Find yours at ror.org - Consortia are also registered as organisations

2.2 Model Registration (source_id)¶

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

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

Repository: CMIP7-CVs Registered Content

Source IDs will be registered automatically within the CVs once EMD has been completed.

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

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 this issue which tracks the progress and process for adding these lost registrations back into the CV.

Repository: CMIP7-CVs Issues, 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 this issue which tracks the progress and process for adding these lost registrations back into the CV.

Repository: CMIP7-CVs Issues, 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 (WCRP-constants)"] --> B["2. EMD Registration (Essential-Model-Documentation)"]
    B --> C["3. source_id (CMIP7-CVs)"]
    C --> D["4. Experiments (if needed)"]

Step-by-Step Process¶

1. Check if already registered: Before creating a new entry, verify it doesn't already exist in the CV (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 CV

Typical Timeline¶

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

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 try the "General Issue" form for questions.

4. After Registration¶

Once your CVs are registered:

1. esgvoc library will include your entries in the next update
2. You can use your registered identifiers in CMOR tables
3. Your data will 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/

CV Repositories¶

6. Getting Help¶

• General questions: Open a General Issue in the relevant repository
• CV discussions: See Discussions on the CVs repo
• Contact IPO: For complex cases, contact the CMIP International Project Office