CMIP7 Global Attributes, DRS, Filenames, Directory Structure, and CVs

V1.0 Published on 6th October 2025 DOI: 10.5281/zenodo.17250297 CMIP7 Global Attributes, DRS, Filenames, Directory Structure, and CVs Karl E. Taylor, Laurent Troussellier, Sasha Ames, David Hassell, Maria Molina, Zebedee Nicholls, Martin Schupfner, James Anstey, Daniel Ellis, Elisabeth Dingley, Paul J. Durack, Guillaume Levavasseur, Matthew Mizielinski, and Marie-Pierre Moine. Executive Summary In files containing CMIP model-simulation output, global attributes are used to describe the source of the data, the imposed experiment conditions, the contents of the file, licensing restrictions, and other information useful to those analysing the data. Here we define the global attributes that should appear in CMIP7 files (some are required, others optional), along with the so-called CMIP7 “data reference syntax” (DRS). The subset of global attributes that defines the DRS is used in constructing the directory structure and file names found in the CMIP7 archive, and also to construct URL’s leading to further information about the simulations and in populating search facets. Introduction As in earlier phases of CMIP, a well-defined set of global attributes will be recorded in each CMIP7 model output file, providing information necessary for interpreting the data. Table 1 contains the list of CMIP7 global attributes and indicates which ones are required and which are optional. The values for many of the global attributes must be drawn from special CMIP7 “controlled vocabularies” (CVs). A CV, in simplest form, is a list of the permitted values that can be assigned to a given global attribute. Some of these lists of permitted values appear in this document, but they should not be relied on to be 100% correct. Rather, consult the reference CVs for CMIP7, which are available at https://github.com/WCRP-CMIP/CMIP7_CVs/1 Documents of related interest may be found at https://wcrp-cmip.github.io/cmip7-guidance/, which will be updated as more guidance documents are created. 1 At the time of publication of v1.0 of this document, the CMIP7 CVs content is still being compiled. Users can see the latest status of the CVs via the link above. V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Mandatory Global Attributes CMIP7 global attribute name ESGVOC2 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? activity_id activityDD activity identifier "PMIP", "CMIP", "CFMIP", "ScenarioMIP " CV always registered by activity ("MIP") This is the activity most-directly responsible for the experiment. Note: activity i.d. should not include a phase (e.g., "PMIP", not "PMIP3"). Unlike in CMIP6, each experiment and each data set must "belong" to a single activity. yes activity area_label areaLabelDD identifier of unmasked area type "lnd", "air", "sea", "u" CV always assigned based on a forthcoming look-up table Label identifying unmasked area type for which data have been reported. This is set to "u" when data are "unmasked". unmasked area branded_variable brandedVariableDD full branded variable name "tas_tavgh2m-hxy-u", "pr_tpt-uhxy-u", "ua_tavgp19-hxy-air" template always <variable_id>_ <branding_suff ix> The branded variable name is constructed by concatenating the variable_id and the branding_suffix, separated by an underscore. branding_suffix brandingSuffixDD suffix in the branded variable name "tavg-h2mhxy-u" "tpt-u-hxy-u" “tavg-p19hxy-air" template always <temporal_lab el>- <vertical_label >- <horizontal_lab el>- <area_label> The branding suffix captures information about how the variable is sampled in time, in the vertical and horizontally, as well as indicating masking of the data over certain area types. It is constructed by concatenating the temporal_label, vertifcal_label, horizontal_label and area_label, separating each by an underscore. yes yes branding suffix Conventions dataConventionsDD CF version governing data (along with any other conventions applied) "CF-1.12" template always "CF-"<X.Y> This is a global attribute recognized by the CF conventions. The data requirements conform with "CF-1.12". creation_date dateCreatedDD date the file was created "2025-0821T04:23:12Z " template always <YYYY-MMDD>"T"<HH:MM :SS>"Z" data_specs_version datasetSpecsDD version label for the set of requirements and CVs followed in creating a file "MIPDS7.1.0.0" template always "MIPDS7."<i>.<j>.<k > For CMIP7, the prefix is "MIP-DS7" ("MIP Data Specifications 7") followed by three integers, i, j, and k, separated by periods. "i" is incremented whenever rules governing structure. format, and required content of files are modified. "j" is incremented whenever the structure of one or more CVs is modified. "k" is incremented whenever a new entry (or collection of entries) is added to one or more CVs. 2 ESGVOC is a Python library designed to simplify interaction with controlled vocabularies (CVs) used in WCRP climate data projects: https://esgf.github.io/esgf-vocab/ V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Mandatory Global Attributes CMIP7 global attribute name ESGVOC2 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? drs_specs drsSpecsDD label identifying the data reference syntax used to name files, define directory trees, and uniquely identify datasets. "MIP-DRS7" singleentry CV always "MIP-DRS7" The data reference syntax (DRS) specifies a set of global attributes and other dataset descriptors that are used in uniquely identifying datasets and constructing filenames and directory structures. For CMIP7, drs_specs is assigned the text string "MIPDRS7". yes experiment_id experimentDD short label identifying the experiment "historical", "piControl", "abrupt4xCO 2" CV always registered by activity ("MIP") The names of experiments are proposed by an activity (MIP) and after review, registered in the CMIP7_CVs_experiment CV. yes yes experiment forcing_index forcingDD index identifying variant of forcing "f1", "f3", "f224" template always "f"<i> This index distinguishes runs conforming to the protocol of the CMIP7 experiment generating the results, but with different variants of forcing applied. One can, for example, distinguish between two historical simulations, one forced with the CMIP7recommended forcing data sets and another forced by a different dataset, which might yield information about how forcing uncertainty affects the simulation. The value selected for the index has no intrinsic meaning. Note that in CMIP6 this index was type "integer", but now it is preceded by "f", and is "text". forcing index frequency reportingIntervalDD reporting frequency "mon", "day", "3hr" CV always WIP, following CMIP6 The interval between successive time-slices reported in the file. This can usually be easily validated against the actual data in the file, but it can be complicated with some calendars and reporting intervals (e.g. months which change size depending on leap years etc.). yes yes frequency grid_label gridLabelDD unique label identifying grid on which data is reported "g33s", "g14c", "g8s", "g8su", "g8sv" CV always registered by modeling group Details on how to register grid labels will be forthcoming. yes yes grid V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Mandatory Global Attributes CMIP7 global attribute name ESGVOC2 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? horizontal_label horizontalLabelDD identifier of horizontal structure/sa mpling "hxy", "hs", "hm" CV always assigned based on a forthcoming look-up table Label identifying whether the variable is a function of longitude and latitude, only latitude, or if it is an area mean, sampled at "sites", or sampled in some other way. horizontal sampling initialization_index initializationDD index indicating initialization method and/or, for decadal predictions, initialization date "i1", "i2", "i196001", "i201001", "i201001a", "i201001b" template always "i"<j>[<a>] This index is for most CMIP7 experiments set to "i1". For decadal prediction experiments <j> is replaced by the year and month when the experiment has been initialized (e.g., "196001"). When a model initializes its prdictions using different initilization methods, then the year/month is folllowed by a single alphbetic character limited to "a" "b", "c", "d", or "e". The letter selected has no intrinsic meaning. Note that in CMIP6 this index was type "integer", but now it is preceded by "i", and is "text". initializatio n index institution_id institutionDD institution acronym "IPSL", "CR", "NCAR" CV (registered content) always registered by modeling group yes institution license_id licenseDD creative commons license identifier "CC-BY4.0", "CC01.0" CV always list of Crative Commons licenses approved by the WIP & CMIP Panel, which will be a small subset of those listed in https://spdx.or g/licenses/ mip_era mipEraDD label to indicate the CMIP phase when an experiment was designed "CMIP7" singleentry CV always "CMIP7" In CMIP7, the MIP era is used to distinguish among the experiments performed during different CMIP phases but with differences in experimental protocol. For example, the "historical" experiments differ across eras but can be distinguished using the "mip_era" global attribute. yes nominal_resolution nominalResolutionDD approximate horizontal resolution "1 km", "250 km", "500 km" CV always calculated according to a standard, specified algorithm (see Appendix 2 of a CMIP7 document) the nominal_resolution characterizes the resolution of the grid on which the data are reported. It is calculated using an algorithm that nearly matches that described in Appendix 2 of a CMIP6 document. nominal resolution V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Mandatory Global Attributes CMIP7 global attribute name ESGVOC2 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? physics_index physicsDD index distinguishin g among simulations generated by the same "source", but with minor differences in physics "p1", "p3", "p224" template always "p"<i> This index distinguishes simulations run under the same conditions but with minor changes in the model physics formulations. The value selected for the index has no intrinsic meaning. Note that in CMIP6 this index was type "integer", but now it is preceded by "p", and is "text". physics index product productTypeDD identifier of data category "modeloutput" singleentry CV always "modeloutput" The "product" identifies what category of data is reported, which is "model_output" for data in the CMIP7 data request. For other activities it might identify the data type as being "observations" "reanalysis", "derived" (i.e., a product derived from a more primary type), etc. realization_index realizationDD index distinguishin g the members of an ensemble initialized from different points in a parent run "f1", "f3", "f224" template always "r"<i> This index distinguishes models that only differ in minor changes in their initial conditions, usually resulting from branching at different points in a control run or from different realizations of a historical run. Different "realizations" are equally likely simulations of model response, differing only due to stochastic variations. Note that in CMIP6 this index was type "integer", but now it is preceded by "r", and is "text". realization index realm realmDD realms most closely associated with a variable "atmos aerosol", "ocean", "atmos atmosChem" CV always list approved by the WIP, based on CMIP6 Note that "realm" may be assigned multiple realms, separated by a single space, with the first one listed considered primary. realm region dataRegionDD the domain over which data are reported "glb" (global), "ant" (Antarctica), "grn" (Greenland) CV always list approved by the WIP yes yes region source_id sourceDD short label identifying the source (model) "CanESM6MR" CV always modeling group registered content yes yes source V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Mandatory Global Attributes CMIP7 global attribute name ESGVOC2 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? temporal_label temporalLabelDD identifier of type of temporal sampling applied "tavg", "tpt", "tclm" CV always assigned based on a forthcoming look-up table Label indicating how the variable has been sampled in the temporally (e.g., a time mean, synoptically, the maximum within the time interval). temporal sampling tracking_id uniqueFileIdDD unique file identifier "hdl:21.14107/ f66354048a1a-4aa9918d3792e8321f0 4" template always "hdl:21.14107"/< uuid> A unique i.d. attached to a file, the tracking_id's uuid should be generated using the OSSP utility which supports a number of different DCE 1.1 variant UUID options. For CMIP7, version 4 (random number based) is required. Download the software from http://www.ossp.org/pkg/lib/uuid/. variable_id variableRootDD variable root name "tas", "ua", "pr" CV always data request The variable_id in CMIP7 is also referred to as "root name" and "out name". Usually all variables associated with a particular "standard name", as defined by the CF conventions, are all assigned a single variable_id, but sometimes the branding_suffix cannot distinguish between variables sharing the same standard_name, so the variable_id may differ. yes yes root name variant_label datasetVariantDD a label distinguishin g among closelyrelated dataset variants "r1i1p1f1", "r2i2p2f1", "r1i198001p1f 1", "r1i198001ap1 f1", "r1i199001bp1 f1" template always <realization_ind ex><initializatio n_index><physi cs_index><forc ing_index> The variant label is constructed from the 4 indexes that distinguish simulations by a single model that differ (within the experiment design constraints) in intialization branch times, initialization method, model physics and/or forcings imposed. yes yes vertical_label verticalLabelDD identifier of vertical sampling applied "h2m", "200hPa", "p19", "ol", "u" CV always assigned based on a forthcoming look-up table Label indicating how the variable has been sampled in the vertical (e.g., on model levels, on certain pressure levels, or at a single vertical level). vertical sampling V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Conditionally Request Global Attributes (see note 2 below table) CMIP7 global attribute name ESGVOC Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? branch_time_in_child - time run was branched from parent consistent with child’s time-model and units 365.0D0 0.0D0 double precision float when parent exists data provider specified If no parent, omit. See note 1 below. branch_time_in_parent - time run was branched from parent consistent with parent's time-model and units 3650.0D0 18250.0D0 double precision float when parent exists data provider specified If no parent, omit. See note 1 below. external_variables - external variable naming cell measures variables “areacella”, “areacello volcello”, "areacello" CV when cell_measu res are specified blankseparated list of the names of variables found in the cell_measures attribute. list of cell measure variables (separated by single spaces) that are referenced but not included in the file. These variables will be stored independently in the CMIP data archive. Omit if cell_measures is absent. parent_activity_id - parent's activity identifier “CMIP”, "ScenarioMIP " CV (registered content) when parent exists registered by activity ("MIP") to help identify parent run (when parent comes from a different MIP); if no parent, omit. parent_experiment_id - parent's experiment identifier “piControl”, "historical" CV (registered content) when parent exists registered by activity ("MIP") If the parent run is immaterial or if an experiment is initialized in some other way (e.g., from observations), then omit. parent_mip_era - parent's mip_era “CMIP6”, “CMIP7” CV when parent exists WIP (usually "CMIP7", but open to possibility of being "CMIP6") with parent_activity_id, this fully defines parent activity; if no parent, omit. parent_source_id - parent's model identifier "CanESM6MR" CV (registered content) when parent exists helps identify parent run; when no parent, omit (see note 2); usually will be the same as source_id. parent_time_units - time units, as recorded in parent file “days since 1850-1-1”, “days since 1000-1-1 (noleap)” (see note 5) template when parent exists "days since "<date>[<calen dar>] without this, a user would have to read the parent file to interpret branch_time_in_parent; the “calendar” modifier is required only if the calendars used by the parent and child differ. If no parent, omit. See note 1 below. parent_variant_label - parent's variant label “r1i1p1f1”, “r1i2p223f3” template when parent exists template is defined by whichever MIP phase defined the parent experiment used to distinguish among variants of the parent; when no parent, omit. V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Optional Global Attributes (see note 2 below table) CMIP7 global attribute name ESGVOC3 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? experiment - short phrase describing the experiment “preindustrial control”, “abrupt quadrupling of CO2” unverified text (see note 2 below) never a description consistent with experiment_id This attribute is optional but strongly recommended as an aid to reminding users what the meaning of the cryptic experiment_id is. The text should be copied from the experiment "description" accessible via an API under development. No QA validation of this attribute is done , and it is subject to correction at any time, so users cannot be certain it has been recorded correctly in the global attribute. The corrected and up-to-date institution description will be accessible through the aforementioned API, and any deviations from the standard experiment protocol (e.g., a different forcing applied) should eventually be recorded in documentation of experiment conformance. history - processing history unverified text (see note 2 below) never data provider composed text The "history" global attribute is recognized by the CF conventions and typically includes an audit trail documenting modifications to the original data. Each modification is typically preceded by a "timestamp". institution - institution name “Meteorologi cal Research Institute” unverified text (see note 2 below) never a description consistent with institution_id This attribute is optional but strongly recommended as an aid to providing a more complete name of the institution than given by institution_id. The text should be copied from the institution "description" accessible via an API under development. No QA validation of this attribute is done , and it is subject to correction at any time, so users cannot be certain it has been recorded correctly in the global attribute. The corrected and up-to-date institution description will be accessible through the aforementioned API. 3 ESGVOC is a Python library designed to simplify interaction with controlled vocabularies (CVs) used in WCRP climate data projects: https://esgf.github.io/esgf-vocab/ V1.0 DOI: 10.5281/zenodo.17250297 Published on 6th October 2025 Optional Global Attributes (see note 2 below table) CMIP7 global attribute name ESGVOC3 Data Descriptor Short description Examples Content constraint When required? (see note 2 below table) Content source or template Further description, rationale, and information In CMIP7 filename? In CMIP7 directory structure? Likely search facet label? license - description of license see CMIP6 license unverified text (see note 2 below) never a description consistent with license_id This attribute is optional but strongly recommended as an aid to providing a more complete description of the license restrictions under the license_id. The text should be copied from the license "description" accessible via an API under development. No QA validation of this attribute is done , and it is subject to correction at any time, so users cannot be certain it has been recorded correctly in the global attribute. The corrected and up-todate institution description can be accessed through the aforementioned API. references - references relevant to the data reported unverified text (see note 2 below) never data provider composed text The "reference" attribute is recognized by the CF conventions. When available, include the DOI (or a URL) associated with any reference material. source - full model name and version unverified text (see note 2 below) never a description consistent with source_id This attribute is optional but strongly recommended as an aid to providing a more complete description of the source than given by source_id. The text should be copied from the source "description" accessible via an API under development. No QA validation of this attribute is done , and it is subject to correction at any time, so users cannot be certain it has been recorded correctly in the global attribute. The corrected and up-todate institution description can be accessed through the aforementioned API. The template used in creating the "source" text will likely be similar to that used in CMIP6 and described in note 3 below. title - short description of dataset unverified text (see note 2 below) never data provider composed text This is a CF-convention recognized global attribute, but with no structure or CV specified. If included, any text is acceptable; a possible title might follow this example: "CMIP7 historical results from the IPSL-CM5 model".