diff --git a/.github/workflows/update_html.yaml b/.github/workflows/update_html.yaml index b14b3b2..a140720 100644 --- a/.github/workflows/update_html.yaml +++ b/.github/workflows/update_html.yaml @@ -11,13 +11,14 @@ jobs: update_html: runs-on: ubuntu-latest name: Update HTML + if: github.event.pull_request.merged == true # Only run if the PR was merged steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: 3.11 @@ -37,25 +38,24 @@ jobs: deploy: runs-on: ubuntu-latest - needs: update_html # Specify that this job depends on the completion of 'update_html' + needs: update_html permissions: contents: read pages: write id-token: write - + steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: ref: gh-pages - name: Setup Pages - uses: actions/configure-pages@v4 + uses: actions/configure-pages@v5 - name: Upload artifact - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@v4 with: - # Upload entire repository path: '.' - name: Deploy to GitHub Pages diff --git a/.github/workflows/update_md.yaml b/.github/workflows/update_md.yaml index 3cf7e92..caee879 100644 --- a/.github/workflows/update_md.yaml +++ b/.github/workflows/update_md.yaml @@ -7,6 +7,8 @@ on: - gh-pages paths: - 'schema/**' + - 'rde_schema/**' + - 'markdown/**' jobs: update_markdown: @@ -15,22 +17,34 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 - - name: Get changed files in the schema folder - id: changed-schema-specific - uses: tj-actions/changed-files@v44 + - name: Get changed files in schema folder + id: changed-schema + uses: tj-actions/changed-files@v47 with: files: schema/** - - name: Prevent from running if no schema files changed - if: steps.changed-schema-specific.outputs.any_changed != 'true' - run: exit 1 + - name: Get changed files in rde_schema folder + id: changed-rde + uses: tj-actions/changed-files@v47 + with: + files: rde_schema/** + + - name: Get changed files in markdown folder + id: changed-markdown + uses: tj-actions/changed-files@v47 + with: + files: markdown/** + + - name: Prevent running if no relevant files changed + if: steps.changed-schema.outputs.any_changed != 'true' && steps.changed-rde.outputs.any_changed != 'true' + run: echo "No relevant changes detected" - name: Set up Python - uses: actions/setup-python@v5 + uses: actions/setup-python@v6 with: python-version: 3.11 @@ -38,16 +52,26 @@ jobs: run: | pip install -r resources/requirements.txt - - name: Generate Schema Documentation + - name: Generate Legacy Schema Documentation + if: steps.changed-schema.outputs.any_changed == 'true' || steps.changed-markdown.outputs.any_changed == 'true' + run: | + python resources/generate_markdown.py \ + --input $GITHUB_WORKSPACE \ + --mode legacy + + - name: Generate Current Schema Documentation + if: steps.changed-rde.outputs.any_changed == 'true' || steps.changed-markdown.outputs.any_changed == 'true' run: | - python resources/generate_markdown_schema.py --source-dir $GITHUB_WORKSPACE + python resources/generate_markdown.py \ + --input $GITHUB_WORKSPACE \ + --mode current - name: Commit and push changes run: | git config user.email "${GITHUB_ACTOR}@users.noreply.github.com" git config user.name "${GITHUB_ACTOR}" git add markdown/ - git commit -am "Generated new copy of schema in markdown" + git diff --cached --quiet || git commit -m "Generated new copy of schema in markdown" git push origin HEAD:$GITHUB_REF - name: Deploy to GitHub Pages diff --git a/.gitignore b/.gitignore index 50eb5dd..1dfdbed 100644 --- a/.gitignore +++ b/.gitignore @@ -8,4 +8,16 @@ projects/terms_of_use/ projects/jinja_tests/export_request-*.json projects/datacite/ projects/ddi_doi_cleanup/input/ -projects/ddi_doi_cleanup/output \ No newline at end of file +projects/ddi_doi_cleanup/output +rde_schema/property_bank/contributors.json +rde_schema/property_bank/link_title.json +rde_schema/property_bank/extent_of_processing.json +rde_schema/property_bank/common_data_elements.json +rde_schema/property_bank/deposits.json +rde_schema/property_bank/restrictions.json +rde_schema/property_bank/README.md +rde_schema/property_bank/external_source_id.json +rde_schema/property_bank/languages.json +rde_schema/property_bank/oversamples.json +rde_schema/property_bank/link_url.json +rde_schema/property_bank/study_purpose.json diff --git a/markdown/assets/style.css b/markdown/assets/style.css index bbed6ab..822f4c8 100644 --- a/markdown/assets/style.css +++ b/markdown/assets/style.css @@ -122,7 +122,6 @@ a { } .wy-side-nav-search { - color: #ffffff; background-color: #115BFB; } diff --git a/markdown/icpsr_study_schema.md b/markdown/icpsr_legacy_schema.md similarity index 56% rename from markdown/icpsr_study_schema.md rename to markdown/icpsr_legacy_schema.md index 4b0f159..e852627 100644 --- a/markdown/icpsr_study_schema.md +++ b/markdown/icpsr_legacy_schema.md @@ -1,61 +1,65 @@ -# ICPSR Metadata Schema +# ICPSR Legacy Metadata Schema -Last updated: April 14, 2026 +Last updated: May 12, 2026 -This is the metadata schema used to describe data collections at the Inter-university Consortium for Political and Social Research (ICPSR). These rules and definitions represent ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help ICPSR users -- including data depositors and researchers accessing data -- understand how to use and interpret our metadata. -For a machine-actionable copy of this information, please see the [JSON Schema version](https://github.com/ICPSR/metadata/blob/main/schema/icpsr_study_schema.json). +This metadata schema was used to describe curated data collections at the Inter-university Consortium for Political and Social Research (ICPSR) through approximately 2026. Beginning in 2026, it is being phased out and replaced by [an updated metadata schema](https://icpsr.github.io/metadata/icpsr_metadata_schema/). +These rules and definitions document ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help users – including data depositors and researchers – understand and interpret ICPSR metadata. + +A machine-actionable version of this schema is available in [JSON Schema](https://github.com/ICPSR/metadata/blob/main/schema/icpsr_study_schema.json) format. ## Metadata Elements: Overview -| Property | Required? | Repeatable? | Accepted Values | Description | -| ------------------------------------------------------ | --------- | ----------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Version](#version ) | Yes | No | Number | The current version number for the data collection. | -| [Version Date](#version_date ) | Yes | No | Text | The date on which the current version of the data collection was released by ICPSR. | -| [Original Release Date](#original_release_date ) | No | No | Text | The date on which the data collection was originally released by ICPSR. | -| [Title](#title ) | Yes | No | Text | The official title that describes what the data collection is about, its geographic scope, and the time period it covered. | -| [Alternate Title](#alternate_title ) | No | Yes | Text | The alternate name(s) or acronym(s) commonly used to refer to the data collection. | -| [Link Title](#link_title ) | No | No | Text | The title of an external resource that is included in the ICPSR catalog as a courtesy to users. | -| [Link URL](#link_url ) | No | No | Text | The URL of an external resource that is included in the ICPSR catalog as a courtesy to users. | -| [Principal Investigator](#principal_investigator ) | Yes | Yes | Multi-part; see subfields | The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization. | -| [Citation](#citation ) | No | No | Text | The official way to reference the data collection in writing. | -| [Distributor](#distributor ) | Yes | Yes | Multi-part; see subfields | The organization(s) responsible for distributing the data collection. | -| [Study Number](#study_number ) | Yes | No | Number | A unique, numerical value used by ICPSR to identify and track data collections. | -| [Digital Object Identifier (DOI)](#doi ) | No | No | Text | The registered persistent digital object identifier (DOI) associated with the data collection. | -| [Funding Source](#funding_source ) | No | Yes | Multi-part; see subfields | The sources of funding that supported the data collection. | -| [External Source ID](#external_source_ID ) | No | Yes | Text | A unique identifier supplied by the data depositor. | -| [Summary](#summary ) | Yes | No | Text | A description of the data collection that helps users understand its purpose, substance, and key topics. | -| [Subject Term](#subject_term ) | Yes | Yes | Text | A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection. | -| [Geographic Coverage Area](#geographic_coverage_area ) | Yes | Yes | Text | The geographic locations where the data refer or are related. | -| [Time Period](#time_period ) | Yes | Yes | Multi-part; see subfields | The time period(s) to which the data refer, regardless of when the data were collected. | -| [Collection Date](#collection_date ) | No | Yes | Multi-part; see subfields | The date(s) when the data were physically collected. | -| [Universe](#universe ) | No | No | Text | The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer. | -| [Data Type](#data_type ) | No | Yes | Text | The types of data included in the data collection. | -| [Collection Note](#collection_note ) | No | Yes | Text | Important details about the data collection (like unique authoring, discrepencies, or processing information) that can't be recorded in other metadata elements. | -| [Study Purpose](#study_purpose ) | No | No | Text | The study's main goals and associated research questions. | -| [Study Design](#study_design ) | No | No | Text | The procedures used to contact participants and gather data. | -| [Variable Description](#variable_description ) | No | No | Text | Significant variables (particularly demographic variables) in the data files. | -| [Sampling](#sampling ) | No | No | Text | The methods used to select the subset of the population that data are to be collected from (e.g., simple, systematic, stratified). | -| [Time Method](#time_method ) | No | Yes | Text | The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends. | -| [Data Source](#data_source ) | No | Yes | Text | The source of the data, when that source is external to the data collection and can be independently cited. | -| [Collection Mode](#collection_mode ) | No | Yes | Text | The method(s) or procedure(s) used to collect the data. | -| [Extent of Processing](#extent_of_processing ) | No | Yes | Text | Processing activities and checks performed on the data collection by ICPSR curation staff. | -| [Weight](#weight ) | No | No | Text | The weight variables and the criteria for using them in data analysis or other information about how the data are weighted if no weight variables are present. | -| [Response Rates](#response_rates ) | No | No | Text | The percentage of respondents in the sample who participated in the data collection. | -| [Scale](#scale ) | No | No | Text | Any commonly known scales used to collect data for the data collection (e.g., MMPI, CPI, the Census Occupational Codes, etc.). | -| [Unit of Observation](#unit_of_observation ) | No | Yes | Text | The object(s) of analysis for the data collection, such as an organization, individual, or household. | -| [Smallest Geographic Unit](#smallest_geographic_unit ) | No | No | Text | The smallest geographic unit (e.g., state or census tract) used in the dataset. | -| [Restrictions](#restrictions ) | No | No | Text | Rules about how the data collection can be accessed or used. | -| [Membership Required](#membership_required ) | No | No | boolean | The availability of the data collection in terms of ICPSR membership. Members-only data may only be downloaded by affiliates of ICPSR member institutions who contribute funding to support the data. | -| [Restricted Access](#restricted_access ) | No | No | boolean | General indication of any access restrictions associated with the data collection. More detailed information is provided in the Restrictions element. | -| [Changes to Collection](#changes_to_collection ) | No | Yes | Multi-part; see subfields | A record of how the data collection has changed over time. | -| [Series](#series ) | No | No | Text | A named collection of related studies. | -| [Classification](#classification ) | No | Yes | Text | Topics used to organize data collections and help users explore the ICPSR catalog. | -| [Filesets](#filesets ) | No | Yes | Multi-part; see subfields | The grouping of files in the data collection. | - -## Key for Metadata Element Entries - -Full information for each ICPSR study metadata element includes the following fields: +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Version](#version) | Yes | No | Number | The current version number for the data collection. | +| [Version Date](#version-date) | Yes | No | Text | The date on which the current version of the data collection was released by ICPSR. | +| [Original Release Date](#original-release-date) | No | No | Text | The date on which the data collection was originally released by ICPSR. | +| [Title](#title) | Yes | No | Text | The official title that describes what the data collection is about, its geographic scope, and the time period it covered. | +| [Alternate Title](#alternate-title) | No | Yes | Text | The alternate name(s) or acronym(s) commonly used to refer to the data collection. | +| [Link Title](#link-title) | No | No | Text | The title of an external resource that is included in the ICPSR catalog as a courtesy to users. | +| [Link URL](#link-url) | No | No | Text | The URL of an external resource that is included in the ICPSR catalog as a courtesy to users. | +| [Principal Investigator](#principal-investigator) | Yes | Yes | Multi-part element; see subfields | The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization. | +| [Citation](#citation) | No | No | Text | The official way to reference the data collection in writing. | +| [Distributor](#distributor) | Yes | Yes | Multi-part element; see subfields | The organization(s) responsible for distributing the data collection. | +| [Study Number](#study-number) | Yes | No | Number | A unique, numerical value used by ICPSR to identify and track data collections. | +| [Digital Object Identifier (DOI)](#digital-object-identifier-(doi)) | Yes | No | Text | The registered persistent digital object identifier (DOI) associated with the data collection. | +| [Funding Source](#funding-source) | No | Yes | Multi-part element; see subfields | The sources of funding that supported the data collection. | +| [External Source ID](#external-source-id) | No | Yes | Text | A unique identifier supplied by the data depositor. | +| [Summary](#summary) | Yes | No | Text | A description of the data collection that helps users understand its purpose, substance, and key topics. | +| [Subject Term](#subject-term) | Yes | Yes | Text | A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection. | +| [Geographic Coverage Area](#geographic-coverage-area) | Yes | Yes | Text | The geographic locations where the data refer or are related. | +| [Time Period](#time-period) | Yes | Yes | Multi-part element; see subfields | The time period(s) to which the data refer, regardless of when the data were collected. | +| [Collection Date](#collection-date) | No | Yes | Multi-part element; see subfields | The date(s) when the data were physically collected. | +| [Universe](#universe) | No | No | Text | The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer. | +| [Data Type](#data-type) | No | Yes | Text | The types of data included in the data collection. | +| [Collection Note](#collection-note) | No | Yes | Text | Important details about the data collection (like unique authoring, discrepencies, or processing information) that can't be recorded in other metadata elements. | +| [Study Purpose](#study-purpose) | No | No | Text | The study's main goals and associated research questions. | +| [Study Design](#study-design) | No | No | Text | The procedures used to contact participants and gather data. | +| [Variable Description](#variable-description) | No | No | Text | Significant variables (particularly demographic variables) in the data files. | +| [Sampling](#sampling) | No | No | Text | The methods used to select the subset of the population that data are to be collected from (e.g., simple, systematic, stratified). | +| [Time Method](#time-method) | No | Yes | Text | The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends. | +| [Data Source](#data-source) | No | Yes | Text | The source of the data, when that source is external to the data collection and can be independently cited. | +| [Collection Mode](#collection-mode) | No | Yes | Text | The method(s) or procedure(s) used to collect the data. | +| [Extent of Processing](#extent-of-processing) | No | Yes | Text | Processing activities and checks performed on the data collection by ICPSR curation staff. | +| [Weight](#weight) | No | No | Text | The weight variables and the criteria for using them in data analysis or other information about how the data are weighted if no weight variables are present. | +| [Response Rates](#response-rates) | No | No | Text | The percentage of respondents in the sample who participated in the data collection. | +| [Scale](#scale) | No | No | Text | Any commonly known scales used to collect data for the data collection (e.g., MMPI, CPI, the Census Occupational Codes, etc.). | +| [Unit of Observation](#unit-of-observation) | No | Yes | Text | The object(s) of analysis for the data collection, such as an organization, individual, or household. | +| [Smallest Geographic Unit](#smallest-geographic-unit) | No | No | Text | The smallest geographic unit (e.g., state or census tract) used in the dataset. | +| [Restrictions](#restrictions) | No | No | Text | Rules about how the data collection can be accessed or used. | +| [Membership Required](#membership-required) | No | No | Boolean | The availability of the data collection in terms of ICPSR membership. Members-only data may only be downloaded by affiliates of ICPSR member institutions who contribute funding to support the data. | +| [Restricted Access](#restricted-access) | No | No | Boolean | General indication of any access restrictions associated with the data collection. More detailed information is provided in the Restrictions element. | +| [Changes to Collection](#changes-to-collection) | No | Yes | Multi-part element; see subfields | A record of how the data collection has changed over time. | +| [Series](#series) | No | No | Text | A named collection of related studies. | +| [Classification](#classification) | No | Yes | Text | Topics used to organize data collections and help users explore the ICPSR catalog. | +| [Filesets](#filesets) | No | Yes | Multi-part element; see subfields | The grouping of files in the data collection. | + +--- + +## Key for Legacy ICPSR Metadata Schema Entries + +Full information for each legacy ICPSR study metadata element includes the following fields: - **Description:** A short description of the metadata element and the information it is intended to convey. - **Required:** Indicates whether the metadata element is mandatory ("Yes") or optional ("No"). Required elements must include at least one value. @@ -66,736 +70,779 @@ Full information for each ICPSR study metadata element includes the following fi - **ICPSR Input Guidance:** Information for ICPSR staff related to using internal tools and resources to create and input metadata values. These notes are made available to the general ICPSR community for transparency. - **Examples:** Examples of valid values for the metadata element. + +--- ## Metadata Elements: Detailed Information -### 1. Version + +### Version **Description:** The current version number for the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Controlled Vocabulary:** N/A -**Usage Notes:** Version numbers are integers without leading zeros. Versioning begins when a data collection is first archived. Each subsequent update of the data collection increments the version number by 1. The version number is incremented when modifying or adding: +**Usage Notes:** Version numbers are integers without leading zeros. Versioning begins when a data collection is first archived. Each subsequent update of the data collection increments the version number by 1. The version number is incremented when modifying or adding: - * Data files, including additions of datasets or supplemental data files, additional masking, increasing curation level, or resupplied datasets - * Documentation files - * SDA (Survey Documentation and Analysis) files + * Data files, including additions of datasets or supplemental data files, additional masking, increasing curation level, or resupplied datasets + * Documentation files + * SDA (Survey Documentation and Analysis) files -Metadata-only updates to the data collection do not increment the version number. Changes to the version number require a textual summary to be added to Changes to Collection. +Metadata-only updates to the data collection do not increment the version number. Changes to the version number require a textual summary to be added to Changes to Collection. -**Examples:** +**Examples:** -```json -1 +```text +"1" ``` -```json -2 +```text +"2" ``` -### 2. Version Date + +--- + + +### Version Date **Description:** The date on which the current version of the data collection was released by ICPSR. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text (formatted as a date) +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** ICPSR automatically generates this date for data collection additions and updates. For metadata-only updates, the date remains unchanged. -**Examples:** +**Examples:** -```json +```text "2006-03-30" ``` -```json +```text "2019-05-05" ``` -### 3. Original Release Date + +--- + + +### Original Release Date **Description:** The date on which the data collection was originally released by ICPSR. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text (formatted as a date) +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** ICPSR automatically generates the release date. -**Examples:** +**Examples:** -```json +```text "2001-02-07" ``` -```json +```text "2020-08-12" ``` -### 4. Title - -**Description:** The official title that describes what the data collection is about, its geographic scope, and the time period it covered. -**Required**: Yes +--- -**Repeatable**: No + +### Title -**Accepted Values**: Text +**Description:** The official title that describes what the data collection is about, its geographic scope, and the time period it covered. -**Controlled Vocabulary:** N/A +**Required:** Yes -**Usage Notes:** The Title includes three essential parts: the title proper, the geography, and the time period. +**Repeatable:** No -Title Proper: +**Accepted Values:** Text - * The title proper is a descriptive string that captures what the data collection contains. +**Controlled Vocabulary:** N/A - * The title proper uses title case: all major words are capitalized, while minor words are lowercased. +**Usage Notes:** The Title includes three essential parts: the title proper, the geography, and the time period. - * For new studies, ICPSR starts with the title proper provided by the data depositor. Most title propers are straightforward about their contents, such as the 'American Community Survey' or the 'Census of Law Enforcement Training Academies.' Some title propers include a more branded description, such as 'Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project or Contents' and 'Contexts of Cyberbullying: An Epidemiologic Study using Electronic Detection and Social Network Analysis.' +Title Proper: - * For updated studies, ICPSR uses the existing title in production, making changes as necessary to add new years or additional geographical locations. For studies that are part of an ICPSR series, titles remain consistent with the previous series studies. + * The title proper is a descriptive string that captures what the data collection contains. + + * The title proper uses title case: all major words are capitalized, while minor words are lowercased. -Geography: + * For new studies, ICPSR starts with the title proper provided by the data depositor. Most title propers are straightforward about their contents, such as the 'American Community Survey' or the 'Census of Law Enforcement Training Academies.' Some title propers include a more branded description, such as 'Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project or Contents' and 'Contexts of Cyberbullying: An Epidemiologic Study using Electronic Detection and Social Network Analysis.' - * All titles include the data collection's geography. If the geography is already included in the title proper, it is not repeated. + * For updated studies, ICPSR uses the existing title in production, making changes as necessary to add new years or additional geographical locations. For studies that are part of an ICPSR series, titles remain consistent with the previous series studies. - * Cities are paired with state or province names that are spelled out (e.g., Portland, Oregon), unless the city names are unique or well-known. +Geography: - * Studies with more than four geographic locations typically are summarized using, for example, '5 countries,' '8 German cities,' '20 U.S. states' instead of listing all locations. In the latter case, 'U.S.' is used rather than 'United States' or 'American'. + * All titles include the data collection's geography. If the geography is already included in the title proper, it is not repeated. + + * Cities are paired with state or province names that are spelled out (e.g., Portland, Oregon), unless the city names are unique or well-known. - * Descriptors that do not have a distinct geographic area, such as 'communities' or 'regions', are not included in titles. + * Studies with more than four geographic locations typically are summarized using, for example, '5 countries,' '8 German cities,' '20 U.S. states' instead of listing all locations. In the latter case, 'U.S.' is used rather than 'United States' or 'American'. + + * Descriptors that do not have a distinct geographic area, such as 'communities' or 'regions', are not included in titles. - * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. + * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. - * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has “National” in the title, or a similar word specific to that country. + * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has "National" in the title, or a similar word specific to that country. -Time Period: +Time Period: - * All titles include the data collection's time period, which reflects the time period that the data collection covers and should match the Time Period. For example, in the 'Uganda Elite Study, 1964-1968', it is assumed that the Ugandans were surveyed about events in 1964-1968, even if the actual data collection might not have taken place until later. + * All titles include the data collection's time period, which reflects the time period that the data collection covers and should match the Time Period. For example, in the 'Uganda Elite Study, 1964-1968', it is assumed that the Ugandans were surveyed about events in 1964-1968, even if the actual data collection might not have taken place until later. - * If the time period is already included in the title proper, it is not repeated. + * If the time period is already included in the title proper, it is not repeated. - * For most studies, a single year or range of years is acceptable. Years are written as four digits, including when used in a range (e.g., '1999', '2001-2003', or '1999, 2010, 2015'). + * For most studies, a single year or range of years is acceptable. Years are written as four digits, including when used in a range (e.g., '1999', '2001-2003', or '1999, 2010, 2015'). - * Months are included only when part of ICPSR series that have multiple releases, which are otherwise identical, each year. In these cases, months are spelled out (e.g., 'September 2020' instead of '9/2020' or 'Sept. 2020'). + * Months are included only when part of ICPSR series that have multiple releases, which are otherwise identical, each year. In these cases, months are spelled out (e.g., 'September 2020' instead of '9/2020' or 'Sept. 2020'). -**Examples:** +**Examples:** -```json +```text "Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project, Kansas City, Missouri, 2014-2017" ``` -```json +```text "Health and Relationships Project, United States, 2014-2015" ``` -```json +```text "Targeted Interventions to Prevent Chronic Low Back Pain in High Risk Patients: A Multi-Site Pragmatic Randomized Controlled Trial (TARGET Trial), 4 U.S. cities, 2016-2019" ``` -```json +```text "Aid Like A Paycheck (ALAP), Texas and California, 2014-2017" ``` -```json +```text "COVID-19 Disruptions Disproportionately Affect Female Academics, Global, 2020" ``` -### 5. Alternate Title + +--- + + +### Alternate Title **Description:** The alternate name(s) or acronym(s) commonly used to refer to the data collection. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Alternate Title often takes the form of a shortened (by abbreviation or acronym) version of the official title. -**Examples:** +**Examples:** -```json -[ - "Add Health Parent Study" -] +```text +"Add Health Parent Study" ``` -```json -[ - "FACES 2009" -] +```text +"FACES 2009" ``` -```json -[ - "Surveys of Consumers" -] +```text +"Surveys of Consumers" ``` -```json -[ - "Eurobarometer 85.2" -] +```text +"Eurobarometer 85.2" ``` -### 6. Link Title + +--- + + +### Link Title **Description:** The title of an external resource that is included in the ICPSR catalog as a courtesy to users. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Always appears with the Link URL. -**Example:** +**Examples:** -```json +```text "Cebu Longitudinal Health and Nutrition Survey" ``` -### 7. Link URL + +--- + + +### Link URL **Description:** The URL of an external resource that is included in the ICPSR catalog as a courtesy to users. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Always appears with the Link Title. -**Example:** +**Examples:** -```json +```text "https://cebu.cpc.unc.edu/" ``` -### 8. Principal Investigator + +--- + + +### Principal Investigator **Description:** The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization. -**Required**: Yes +**Required:** Yes -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields **Controlled Vocabulary:** The [ICPSR Personal Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) and [Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) are the primary authority control sources for PI names. The [Virtual International Authority File](https://viaf.org/) (VIAF) serves as a secondary resource if names are not present in ICPSR lists. -**Usage Notes:** List individuals and organizations that are chiefly responsible for the study across its entire life cycle or made significant intellectual contributions to the research. A principal investigator (PI) may be a person or an organization; use the Person or Organization element as appropriate. If the PI is identified as a person, their affiliated organization (if applicable) should be included in the Organization element. +**Usage Notes:** List individuals and organizations that are chiefly responsible for the study across its entire life cycle or made significant intellectual contributions to the research. A principal investigator (PI) may be a person or an organization; use the Person or Organization element as appropriate. If the PI is identified as a person, their affiliated organization (if applicable) should be included in the Organization element. -When entering the name of an individual or organizational PI, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: +When entering the name of an individual or organizational PI, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: - 1. If the person or organization has published data with ICPSR in the past, use the name as it has been displayed previously within the ICPSR catalog. - 2. If the person or organization is in the [ICPSR Personal Name Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) or the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. - 3. If the person or organization is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). - 4. If the person or organization does not have a VIAF record, consult another authoritative source, such as an organization's website, Google Scholar, or a personal C.V. published on an institutional website. + 1. If the person or organization has published data with ICPSR in the past, use the name as it has been displayed previously within the ICPSR catalog. + 2. If the person or organization is in the [ICPSR Personal Name Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) or the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. + 3. If the person or organization is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). + 4. If the person or organization does not have a VIAF record, consult another authoritative source, such as an organization's website, Google Scholar, or a personal C.V. published on an institutional website. -For the names of people: +For the names of people: + + * The given (i.e., 'first') name may include the middle name or initial. If the person only uses an inital for the given name, do not include a space between first and middle initials (e.g., 'E.V.'). + * The family (i.e., 'last') name can include any suffixes (such as 'II' or 'Jr.'). + * Abbreviations are discouraged (especially 'et al.'). - * The given (i.e., 'first') name may include the middle name or initial. If the person only uses an inital for the given name, do not include a space between first and middle initials (e.g., 'E.V.'). - * The family (i.e., 'last') name can include any suffixes (such as 'II' or 'Jr.'). - * Abbreviations are discouraged (especially 'et al.'). +For the names of organizations: -For the names of organizations: + * Include the full hierarchy of the organization, going from the highest level down to the most specific. Note that the higher level of the organization must be listed before the lower level, and levels should be separated by a period (e.g., 'University of Michigan. College of Literature, Science, and the Arts'). There is no period following the last level listed. + * Abbreviations are discouraged, except 'Inc.' and 'Co.' In particular, governmental PI's are spelled out completely (e.g., 'United States Department of Commerce' rather than 'U.S. Dept. of Commerce'). + * 'The' is not included at the start of an organization name unless it is actually part of the official name (e.g., 'The New York Times' but not 'The National Institute of Justice') - * Include the full hierarchy of the organization, going from the highest level down to the most specific. Note that the higher level of the organization must be listed before the lower level, and levels should be separated by a period (e.g., 'University of Michigan. College of Literature, Science, and the Arts'). There is no period following the last level listed. - * Abbreviations are discouraged, except 'Inc.' and 'Co.' In particular, governmental PI's are spelled out completely (e.g., 'United States Department of Commerce' rather than 'U.S. Dept. of Commerce'). - * 'The' is not included at the start of an organization name unless it is actually part of the official name (e.g., 'The New York Times' but not 'The National Institute of Justice') +Additional points regarding affiliated organizations: + + * If a PI's organizational affiliation is not known, use the term 'Unknown' in the PI Organization element. + * If multiple PIs (people) are affiliated with the same organization, the affiliated organization's name must be included for each person. -Additional points regarding affiliated organizations: +#### Subfields: - * If a PI's organizational affiliation is not known, use the term 'Unknown' in the PI Organization element. - * If multiple PIs (people) are affiliated with the same organization, the affiliated organization's name must be included for each person. +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Person](#principal-investigator_person) | Conditional | No | Multi-part element; see subfields | The name of a person primarily responsible for the data collection. | +| [Organization](#principal-investigator_organization) | Conditional | No | Text | The name of the organization primarily responsible for the data collection OR the organization with which an individual PI was affiliated at the time of a data collection's deposit at ICPSR. | +| [Order](#principal-investigator_order) | Yes | No | Number | The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI. | -#### 8.1. Subfields: + +##### Person -| Property | Required? | Repeatable? | Accepted Values | Description | -| ----------------------------------------------------------- | --------- | ----------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Person](#principal_investigator_items_person ) | No | No | Multi-part; see subfields | The name of a person primarily responsible for the data collection. | -| [Organization](#principal_investigator_items_organization ) | No | No | Text | The name of the organization primarily responsible for the data collection OR the organization with which an individual PI was affiliated at the time of a data collection's deposit at ICPSR. | -| [Order](#principal_investigator_items_order ) | Yes | No | Number | The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI. | +**Description:** The name of a person primarily responsible for the data collection. -##### 8.1.1. Person +**Required:** Conditional (must include either Person or Organization) -**Description:** The name of a person primarily responsible for the data collection. +**Repeatable:** No -**Required**: No +**Accepted Values:** Multi-part element; see subfields -**Repeatable**: No +##### Subfields: -**Accepted Values**: Multi-part element; see subfield definitions for more information. +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Given (First) Name](#principal-investigator_person_given_name) | Yes | No | Text | The person's given name. | +| [Family (Last) Name](#principal-investigator_person_family_name) | Yes | No | Text | The person's family name (e.g., surname). | -| Property | Required? | Repeatable? | Accepted Values | Description | -| ---------------------------------------------------------------- | --------- | ----------- | --------------- | ----------------------------------------- | -| [Given Name](#principal_investigator_items_person_given_name ) | Yes | No | Text | The person's given name. | -| [Family Name](#principal_investigator_items_person_family_name ) | Yes | No | Text | The person's family name (e.g., surname). | + +###### Given (First) Name -**Examples:** +**Description:** The person's given name. -```json -{ - "given_name": "James A.", - "family_name": "McCann" -} -``` +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text -```json -{ - "given_name": "Warren", - "family_name": "Winkelstein Jr." -} +**Examples:** + +```text +"James A." ``` -```json -{ - "given_name": "E.V.", - "family_name": "Oppenhuis" -} +```text +"Lois" ``` -```json -{ - "given_name": "Miner P.", - "family_name": "Marchbanks III" -} +```text +"E.V." ``` -###### 8.1.1.1. Given Name + +###### Family (Last) Name -**Description:** The person's given name. +**Description:** The person's family name (e.g., surname). -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text -###### 8.1.1.2. Family Name +**Examples:** -**Description:** The person's family name (e.g., surname). +```text +"McCann Jr." +``` + +```text +"Smith" +``` -**Required**: Yes +```text +"Oppenhuis" +``` + +#### Complete Person Examples (with Subfields): + +```yaml +"Given (First) Name": "James A." +"Family (Last) Name": "McCann Jr." +``` -**Repeatable**: No +```yaml +"Given (First) Name": "Lois" +"Family (Last) Name": "Smith" +``` -**Accepted Values**: Text +```yaml +"Given (First) Name": "E.V." +"Family (Last) Name": "Oppenhuis" +``` -##### 8.1.2. Organization + +##### Organization **Description:** The name of the organization primarily responsible for the data collection OR the organization with which an individual PI was affiliated at the time of a data collection's deposit at ICPSR. -**Required**: No +**Required:** Conditional (must include either Person or Organization) -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text -**Examples:** +**Examples:** -```json +```text "University of Michigan" ``` -```json +```text "Harvard University. Medical School" ``` -```json +```text "University of California, Irvine" ``` -```json +```text "United States Department of Health and Human Services. Centers for Disease Control and Prevention. Office of Minority Health and Health Disparities" ``` -##### 8.1.3. Order + +##### Order **Description:** The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Controlled Vocabulary:** N/A **Usage Notes:** A value of '1' indicates the primary PI, '2' the second, and so forth. -**Examples:** +**Examples:** -```json -1 +```text +"1" ``` -```json -2 +```text +"2" ``` -```json -3 +```text +"3" ``` -###### Complete Principal Investigator Examples (with Subfields): -```json -[ - { - "person": { - "given_name": "Jane", - "family_name": "Doe" - }, - "organization": "Urban Institute", - "order": 1 - }, - { - "person": { - "given_name": "John Q.", - "family_name": "Public" - }, - "organization": "Harvard University. Medical School", - "order": 2 - } -] +#### Complete Principal Investigator Examples (with Subfields): + +```yaml +- "Person": + "Given (First) Name": "Jane" + "Family (Last) Name": "Doe" + "Organization": "Urban Institute" + "Order": 1 + +- "Person": + "Given (First) Name": "John Q." + "Family (Last) Name": "Public" + "Organization": "Harvard University. Medical School" + "Order": 2 ``` -```json -[ - { - "organization": "Urban Institute", - "order": 1 - } -] +```yaml +- "Organization": "Urban Institute" + "Order": 1 ``` -### 9. Citation + +--- + + +### Citation **Description:** The official way to reference the data collection in writing. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** The Citation is dynamically assembled from other entry elements in this format: Principal-Investigator-list. Study-Title. Distributor-list, Version-Date. DOI. ICPSR 'union catalog' records – i.e., external resource to which ICPSR links as a courtesy – do not have citations generated. +**Usage Notes:** The Citation is dynamically assembled from other entry elements in this format: Principal-Investigator-list. Study-Title. Distributor-list, Version-Date. DOI. ICPSR 'union catalog' records (i.e., external resource to which ICPSR links as a courtesy) do not have citations generated. -For additional information about how DOIs for citations are generated, see the Digital Object Identifier element usage notes. +For additional information about how DOIs for citations are generated, see the Digital Object Identifier element usage notes. -**Examples:** +**Examples:** -```json -[ - "University of Michigan. Survey Research Center. Economic Behavior Program. Survey of Consumer Attitudes and Behavior, September 2018. Inter-university Consortium for Political and Social Research [distributor], 2021-11-18. https://doi.org/10.3886/ICPSR38121.v1" -] +```text +"University of Michigan. Survey Research Center. Economic Behavior Program. Survey of Consumer Attitudes and Behavior, September 2018. Inter-university Consortium for Political and Social Research [distributor], 2021-11-18. https://doi.org/10.3886/ICPSR38121.v1" ``` -```json -[ - "Goldin, Claudia, and Lawrence Katz. The 1915 Iowa State Census Project. ICPSR28501-v1. Ann Arbor, MI: Inter-university Consortium for Political and Social Research [distributor], 2010-12-14. http://doi.org/10.3886/ICPSR28501.v1" -] +```text +"Goldin, Claudia, and Lawrence Katz. The 1915 Iowa State Census Project. ICPSR28501-v1. Ann Arbor, MI: Inter-university Consortium for Political and Social Research [distributor], 2010-12-14. http://doi.org/10.3886/ICPSR28501.v1" ``` -### 10. Distributor + +--- + + +### Distributor **Description:** The organization(s) responsible for distributing the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields -**ICPSR Input Guidance:** Most data collections list ICPSR as the distributor. As such, the full name and location of ICPSR are easily accessible in the metadata editor. +**ICPSR Input Guidance:** Most data collections list ICPSR as the distributor. As such, the full name and location of ICPSR are easily accessible in the metadata editor. If a non-ICPSR distributor is necessary, please confirm the standards with the Metadata Librarian. Please note that external distributors are often appropriate for Union Catalog entries and metadata-only releases. -#### 10.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| ---------------------------------------- | --------- | ----------- | --------------- | -------------------------------------------------------------------- | -| [Name](#distributor_items_name ) | Yes | No | Text | The name of the data distributor. | -| [Location](#distributor_items_location ) | Yes | No | Text | The location of the data distributor. | -| [Order](#distributor_items_order ) | Yes | No | Number | The order of importance for the distributors of the data collection. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Name](#distributor_name) | Yes | No | Text | The name of the data distributor. | +| [Location](#distributor_location) | Yes | No | Text | The location of the data distributor. | +| [Title](#distributor_order) | Yes | No | Number | The order of importance for the distributors of the data collection. | -##### 10.1.1. Name + +##### Name **Description:** The name of the data distributor. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) -**Examples:** +**Examples:** -```json +```text "Inter-university Consortium for Political and Social Research" ``` -```json +```text "Roper Center for Public Opinion Research" ``` -##### 10.1.2. Location + +##### Location **Description:** The location of the data distributor. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Include the city and state (or country) where the distributor is located. -**Examples:** +**Examples:** -```json +```text "Ann Arbor, MI" ``` -```json +```text "Chicago, IL" ``` -##### 10.1.3. Order + +##### Title **Description:** The order of importance for the distributors of the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Controlled Vocabulary:** N/A **Usage Notes:** A value of '1' indicates the primary distributor, '2' the second, and so forth. -**Examples:** +**Examples:** -```json -1 +```text +"1" ``` -```json -2 +```text +"2" ``` -```json -3 +```text +"3" ``` -###### Complete Distributor Examples (with Subfields): -```json -[ - { - "name": "Inter-university Consortium for Political and Social Research", - "location": "Ann Arbor, MI", - "order": 1 - } -] +#### Complete Distributor Examples (with Subfields): + +```yaml +- "Name": "Inter-university Consortium for Political and Social Research" + "Location": "Ann Arbor, MI" + "Title": 1 ``` -```json -[ - { - "name": "Inter-university Consortium for Political and Social Research", - "location": "Ann Arbor, MI", - "order": 1 - }, - { - "name": "Roper Center for Public Opinion Research", - "location": "Princeton, NJ", - "order": 2 - } -] +```yaml +- "Name": "Inter-university Consortium for Political and Social Research" + "Location": "Ann Arbor, MI" + "Title": 1 + +- "Name": "Roper Center for Public Opinion Research" + "Location": "Princeton, NJ" + "Title": 2 ``` -### 11. Study Number + +--- + + +### Study Number **Description:** A unique, numerical value used by ICPSR to identify and track data collections. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Controlled Vocabulary:** N/A **Usage Notes:** The study number is automatically generated by ICPSR and is unique. Current study numbers are five digits, though four digit numbers were once standard and are still acceptable. -**Examples:** +**Examples:** -```json -2760 +```text +"2760" ``` -```json -3025 +```text +"3025" ``` -```json -38672 +```text +"38672" ``` -### 12. Digital Object Identifier (DOI) + +--- + + +### Digital Object Identifier (DOI) **Description:** The registered persistent digital object identifier (DOI) associated with the data collection. -**Required**: No +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text (formatted as a URL) +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** The DOI (digital object identifier) is a persistent identifier provided by DataCite, a DOI registration agency. The DOI name is divided into three parts, separated by slashes ('/'): 'https://doi.org' is the HTTP URL link; followed by '10.3886', a globally unique number that identifies ICPSR as the registrant within the DOI namespace; followed by 'ICPSR', the ICPSR study number, and then the version number. The study number is automatically generated by ICPSR and is unique. Current study numbers are five digits, though four digit numbers were once standard and are still acceptable. Studies with fewer than five digits will have zeroes prepended in the DOI (e.g., '10.3886/ICPSR02760). -**Examples:** +**Examples:** -```json +```text "https://doi.org/10.3886/ICPSR03025.v2" ``` -```json +```text "https://doi.org/10.3886/ICPSR06425.v1" ``` -### 13. Funding Source + +--- + + +### Funding Source **Description:** The sources of funding that supported the data collection. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields -#### 13.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| --------------------------------------------------- | --------- | ----------- | ------------------------- | -------------------------------------------------------------------------- | -| [Agency](#funding_source_items_agency ) | Yes | No | Text | An organization that supported the data collection. | -| [Grant Number](#funding_source_items_grant_number ) | No | Yes | Text | A unique identifier associated with the funding. | -| [Purpose](#funding_source_items_purpose ) | No | Yes | Text | The purpose of the funding. | -| [Order](#funding_source_items_order ) | Yes | No | Number | The relative order of funding sources associated with the data collection. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Agency](#funding-source_agency) | Yes | No | Text | An organization that supported the data collection. | +| [Grant Number](#funding-source_grant_number) | No | Yes | Text | A unique identifier associated with the funding. | +| [Purpose](#funding-source_purpose) | No | Yes | Text | The purpose of the funding. | +| [Order](#funding-source_order) | Yes | No | Number | The relative order of funding sources associated with the data collection. | -##### 13.1.1. Agency + +##### Agency **Description:** An organization that supported the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** The [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) is the primary authority control source for funding agencies. The [Virtual International Authority File](https://viaf.org/) (VIAF) serves as a secondary resource if names are not present in the ICPSR list. -**Usage Notes:** When entering the name of a funding agency, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: +**Usage Notes:** When entering the name of a funding agency, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: - 1. If the funding agency has sponsored archived data at ICPSR, use the name as it has been displayed previously within the ICPSR catalog. - 2. If the funding agency is in the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. - 3. If the funding agency is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). - 4. If the funding agency does not have a VIAF record, consult another authoritative source, such as the organization's website or Google Scholar. + 1. If the funding agency has sponsored archived data at ICPSR, use the name as it has been displayed previously within the ICPSR catalog. + 2. If the funding agency is in the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. + 3. If the funding agency is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). + 4. If the funding agency does not have a VIAF record, consult another authoritative source, such as the organization's website or Google Scholar. **ICPSR Input Guidance:** The Principal Investigator's home institution does not need to be listed as a funding agency unless the PI provides a grant number (or other award information) or makes a specific request. -**Examples:** +**Examples:** -```json +```text "United States Department of Justice. Office of Justice Programs. Bureau of Justice Statistics" ``` -```json +```text "Institute of Museum and Library Services" ``` -```json +```text "Robert Wood Johnson Foundation" ``` -##### 13.1.2. Grant Number + +##### Grant Number **Description:** A unique identifier associated with the funding. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Internal blanks in the Grant Number are replaced with hyphens. Multiple grants from the same funding agency are separated by a comma. -**Examples:** +**Examples:** -```json -[ - "SES-1835721" -] +```text +"SES-1835721" ``` -```json -[ - "MDR-8550085", - "MDR-8550204" -] +```text +"MDR-8550085" +"MDR-8550204" ``` -```json -[ - "40791" -] +```text +"40791" ``` -##### 13.1.3. Purpose + +##### Purpose **Description:** The purpose of the funding. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** Local ICPSR controlled vocabulary. See below for terms and definitions: @@ -807,147 +854,146 @@ If a non-ICPSR distributor is necessary, please confirm the standards with the M **ICPSR Input Guidance:** This is an internal ICPSR element that is not publicly displayed. Certain ICPSR topical archives find this useful as they assemble reports for their funding agencies. -**Examples:** +**Examples:** -```json -[ - "collection and/or analysis of data", - "secondary analysis of data" -] +```text +"collection and/or analysis of data" +"secondary analysis of data" ``` -```json -[ - "archiving of data" -] +```text +"archiving of data" ``` -##### 13.1.4. Order + +##### Order **Description:** The relative order of funding sources associated with the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Controlled Vocabulary:** N/A **Usage Notes:** A value of '1' indicates the primary funder, '2' the second, and so forth. -**Examples:** +**Examples:** -```json -1 +```text +"1" ``` -```json -2 +```text +"2" ``` -```json -3 +```text +"3" ``` -###### Complete Funding Source Examples (with Subfields): -```json -[ - { - "agency": "Robert Wood Johnson Foundation", - "grant_numbers": [ - "MDR-8550085", - "MDR-8550204" - ], - "purpose": [ - "collection and/or analysis of data" - ], - "order": 1 - }, - { - "agency": "United States Department of Justice. Office of Justice Programs. Bureau of Justice Statistics", - "grant_numbers": [ - "SES-1835721" - ], - "order": 2 - } -] +#### Complete Funding Source Examples (with Subfields): + +```yaml +- "Agency": "Robert Wood Johnson Foundation" + "Grant Numbers": + - "MDR-8550085" + - "MDR-8550204" + "Purpose": + - "collection and/or analysis of data" + "Order": 1 + +- "Agency": "United States Department of Justice. Office of Justice Programs. Bureau\ + \ of Justice Statistics" + "Grant Numbers": + - "SES-1835721" + "Order": 2 ``` -```json -[ - { - "agency": "Institute of Museum and Library Services", - "order": 1 - } -] +```yaml +- "Agency": "Institute of Museum and Library Services" + "Order": 1 ``` -### 14. External Source ID + +--- + + +### External Source ID **Description:** A unique identifier supplied by the data depositor. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**ICPSR Input Guidance:** This is an internal ICPSR element that is not publicly displayed. An External Source ID consists of: an ICPSR-defined source organization code, a colon, and a Depositor-supplied ID. +**ICPSR Input Guidance:** This is an internal ICPSR element that is not publicly displayed. An External Source ID consists of: -**Examples:** + * an ICPSR-defined source organization code + * a colon + * a Depositor-supplied ID. -```json -[ - "BJS:271" -] +**Examples:** + +```text +"BJS:271" ``` -```json -[ - "PSC:12345" -] +```text +"PSC:12345" ``` -### 15. Summary + +--- + + +### Summary **Description:** A description of the data collection that helps users understand its purpose, substance, and key topics. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** The main goal of the Summary is to give the reader a clear sense of what the data collection is about, including substantive information about the different parts of the data collection not adequately conveyed by the Fileset names or found elsewhere in the metadata. +**Usage Notes:** The main goal of the Summary is to give the reader a clear sense of what the data collection is about, including substantive information about the different parts of the data collection not adequately conveyed by the Fileset names or found elsewhere in the metadata. -A listing of major variables or categories of variables with a few examples is also important. It is also salient to indicate the unit of analysis for the data collection, i.e., who or what is being studied: individuals, housing units, courts, criminal acts, etc. Most often the unit of analysis is the individual; where it is not, it is particularly important to make this clear. +A listing of major variables or categories of variables with a few examples is also important. It is also salient to indicate the unit of analysis for the data collection, i.e., who or what is being studied: individuals, housing units, courts, criminal acts, etc. Most often the unit of analysis is the individual; where it is not, it is particularly important to make this clear. -The Summary is written in the third person and avoids attempting to address issues of how the data might be used, who might be interested in the data, or any evaluative comments about the worth or usefulness of the data collection. The Summary uses past tense when describing the process of collecting the data and present tense when necessary, such as when describing the data (e.g., 'The MIDUS Refresher collection is split into two datasets.'). Numerals are used instead of spelling them out; if a number is spelled out for emphasis, the number is attached in parentheses (e.g. 'Two thousand (2,000)'). +The Summary is written in the third person and avoids attempting to address issues of how the data might be used, who might be interested in the data, or any evaluative comments about the worth or usefulness of the data collection. The Summary uses past tense when describing the process of collecting the data and present tense when necessary, such as when describing the data (e.g., 'The MIDUS Refresher collection is split into two datasets.'). Numerals are used instead of spelling them out; if a number is spelled out for emphasis, the number is attached in parentheses (e.g. 'Two thousand (2,000)'). -**Examples:** +**Examples:** -```json +```text "In 2014, Chicago Public Schools, looking to reduce the possibility of gun violence among school-aged youth, applied for a grant through the National Institute of Justice. CPS was awarded the Comprehensive School Safety Initiative grant and use said grant to establish the 'Connect and Redirect to Respect' program. This program used student social media data to identify and intervene with students thought to be at higher risk for committing violence. At-risk behaviors included brandishing a weapon, instigating conflict online, signaling gang involvement, and threats towards others. Identified at-risk students would be contacted by a member of the CPS Network Safety Team or the Chicago Police Department's Gang School Safety Team, depending on the risk level of the behavior. To evaluate the efficacy of CRR, the University of Chicago Crime Lab compared outcomes for students enrolled in schools that received the program to outcomes for students enrolled in comparison schools, which did not receive the program. 32 schools were selected for the study, with a total of 44,503 students. Demographic variables included age, race, sex, and ethnicity. Misconduct and academic variables included arrest history, in-school suspensions, out-of-school suspensions, GPA, and attendance days." ``` -```json +```text "The Health and Relationship Project is a study of both spouses in same-sex and different-sex marriages who were legally married and aged 35 to 65 at the time of data collection (2015). There are two parts of this study: a baseline questionnaire and a daily diary questionnaire completed for 10 consecutive days; both components were completed online and spouses were asked to complete the surveys separately. The baseline questionnaire asks participants about a number of topics related to marriage and health, including stress, health status and health behaviors, relationship quality, and how they have approached health problems in the past. The diary questionnaire asks participants a number of questions about the past 24 hours, including daily stress experiences, social interactions, and health behaviors." ``` -### 16. Subject Term + +--- + + +### Subject Term **Description:** A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** The [ICPSR Subject Thesaurus](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001) and the [ICPSR Personal Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) are preferred sources. @@ -955,293 +1001,285 @@ The Summary is written in the third person and avoids attempting to address issu **ICPSR Input Guidance:** Non-thesaurus terms can be submitted in the metadata editor and will be reviewed by the metadata librarian. If an ICPSR staff member submits a non-thesaurus term, the metadata librarian will gauge the necessity of this term, check it against the Library of Congress Subject Headings and European Language Social Science Thesaurus to see if a different related term should be used, and consider it for addition to the ICPSR thesaurus. -**Examples:** +**Examples:** -```json -[ - "child care" -] +```text +"child care" ``` -```json -[ - "Social Security", - "crime", - "victimization" -] +```text +"Social Security" +"crime" +"victimization" ``` -```json -[ - "COVID-19", - "Biden, Joe" -] +```text +"COVID-19" +"Biden, Joe" ``` -### 17. Geographic Coverage Area + +--- + + +### Geographic Coverage Area **Description:** The geographic locations where the data refer or are related. -**Required**: Yes +**Required:** Yes -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** [ICPSR Geographic Names Thesaurus](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10003). -**Usage Notes:** Each geographic term's full hierarchy must be included; please note: +**Usage Notes:** Each geographic term's full hierarchy must be included; please note: -* For a U.S. city, the state and country are listed alongside (e.g., 'Los Angeles, California, United States'). -* Non-U.S. geographic subdivisions need not include hierarchical relations, with the specific exceptions of Canadian provinces and the countries within the United Kingdom. -* 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. -* County-level information is typically not indicated. If a U.S. county will be included, the state name and 'United States' must be listed as well. +* For a U.S. city, the state and country are listed alongside (e.g., 'Los Angeles, California, United States'). +* Non-U.S. geographic subdivisions need not include hierarchical relations, with the specific exceptions of Canadian provinces and the countries within the United Kingdom. +* 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. +* County-level information is typically not indicated. If a U.S. county will be included, the state name and 'United States' must be listed as well. -The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names. +The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names. **ICPSR Input Guidance:** The metadata editor will automatically put this element's values in alphabetical order, regardless of hierarchy. For United States-based data collections that include some or all U.S. island territories (e.g., American Samoa, Puerto Rico, Northern Mariana Islands, Virgin Islands of the United States, and Guam), list each of these territories separately in the Geographic Coverage Areas field. -**Examples:** +**Examples:** -```json -[ - "United States", - "Maryland", - "Baltimore" -] +```text +"United States" +"Maryland" +"Baltimore" ``` -```json -[ - "United Kingdom", - "China" -] +```text +"United Kingdom" +"China" ``` -```json -[ - "Canada", - "Alberta" -] +```text +"Canada" +"Alberta" ``` -### 18. Time Period + +--- + + +### Time Period **Description:** The time period(s) to which the data refer, regardless of when the data were collected. -**Required**: Yes +**Required:** Yes -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields -#### 18.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| -------------------------------------------- | --------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Date](#time_period_items_date ) | Yes | No | Text | The date (or date range) for a time period to which the data refer. | -| [Time Frame](#time_period_items_time_frame ) | No | No | Text | An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Date](#time-period_date) | Yes | No | Text | The date (or date range) for a time period to which the data refer. | +| [Time Frame](#time-period_time_frame) | No | No | Text | An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | -##### 18.1.1. Date + +##### Date **Description:** The date (or date range) for a time period to which the data refer. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** Time Periods focus on the dates the data are actually about, regardless of when the data were collected. +**Usage Notes:** Time Periods focus on the dates the data are actually about, regardless of when the data were collected. -Time Periods generally correspond to the dates that appear in the Title; days and months may be included in the Time Period even though they are not in the Title. +Time Periods generally correspond to the dates that appear in the Title; days and months may be included in the Time Period even though they are not in the Title. -Dates are formatted in accordance with ISO 8601 (YYYY, YYYY-MM, or YYYY-MM-DD). One hyphen separates the parts of a date; two hyphens separate two dates. Ranges may be expressed in years (YYYY--YYYY), months (YYYY-MM--YYYY-MM), or days (YYYY-MM-DD--YYYY-MM-DD). No spaces are permitted in date expressions. +Dates are formatted in accordance with ISO 8601 (YYYY, YYYY-MM, or YYYY-MM-DD). One hyphen separates the parts of a date; two hyphens separate two dates. Ranges may be expressed in years (YYYY--YYYY), months (YYYY-MM--YYYY-MM), or days (YYYY-MM-DD--YYYY-MM-DD). No spaces are permitted in date expressions. -**Examples:** +**Examples:** -```json +```text "2020" ``` -```json +```text "2021--2022" ``` -```json +```text "2006-03--2006-04" ``` -```json +```text "2020-01-21--2021-01-21" ``` -##### 18.1.2. Time Frame + +##### Time Frame **Description:** An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** The textual description ('time frame') is used to add context to the Time Period when multiple time periods exist (e.g., to describe different waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. +**Usage Notes:** The textual description ('time frame') is used to add context to the Time Period when multiple time periods exist (e.g., to describe different waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. -The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. +The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. -**Examples:** +**Examples:** -```json +```text "Wave 1" ``` -```json +```text "Spring 2013" ``` -```json +```text "Post-Survey Follow-Up" ``` -###### Complete Time Period Examples (with Subfields): -```json -[ - { - "date": "2020-01-21--2020-06-21", - "time_frame": "Wave 1" - }, - { - "date": "2022-01--2023-01", - "time_frame": "Wave 2" - } -] +#### Complete Time Period Examples (with Subfields): + +```yaml +- "Date": "2020-01-21--2020-06-21" + "Time Frame": "Wave 1" + +- "Date": "2022-01--2023-01" + "Time Frame": "Wave 2" ``` -```json -[ - { - "date": "2020" - } -] +```yaml +- "Date": "2020" ``` -### 19. Collection Date + +--- + + +### Collection Date **Description:** The date(s) when the data were physically collected. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields -#### 19.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| ------------------------------------------------ | --------- | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [Date](#collection_date_items_date ) | Yes | No | Text | The date (or date range) of the data collection period. | -| [Time Frame](#collection_date_items_time_frame ) | No | No | Text | An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Date](#collection-date_date) | Yes | No | Text | The date (or date range) of the data collection period. | +| [Time Frame](#collection-date_time_frame) | No | No | Text | An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | -##### 19.1.1. Date + +##### Date **Description:** The date (or date range) of the data collection period. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Dates are formatted in accordance with ISO 8601 (YYYY, YYYY-MM, or YYYY-MM-DD). One hyphen separates the parts of a date; two hyphens separate two dates. Ranges may be expressed in years (YYYY--YYYY), months (YYYY-MM--YYYY-MM), or days (YYYY-MM-DD--YYYY-MM-DD). No spaces are permitted in date expressions. -**Examples:** +**Examples:** -```json +```text "2020" ``` -```json +```text "2021--2022" ``` -```json +```text "2006-03--2006-04" ``` -```json +```text "2020-01-21--2021-01-21" ``` -##### 19.1.2. Time Frame + +##### Time Frame **Description:** An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** The textual description ('time frame') is used to add context to the Collection Date when multiple time periods exist (e.g., to describe different study waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. +**Usage Notes:** The textual description ('time frame') is used to add context to the Collection Date when multiple time periods exist (e.g., to describe different study waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. -The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. +The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. -**Examples:** +**Examples:** -```json +```text "Wave 1" ``` -```json +```text "Spring 2013" ``` -```json +```text "Post-Survey Follow-Up" ``` -###### Complete Collection Date Examples (with Subfields): -```json -[ - { - "date": "2020-01-21--2020-06-21", - "time_frame": "Wave 1" - }, - { - "date": "2022-01--2023-01", - "time_frame": "Wave 2" - } -] +#### Complete Collection Date Examples (with Subfields): + +```yaml +- "Date": "2020-01-21--2020-06-21" + "Time Frame": "Wave 1" + +- "Date": "2022-01--2023-01" + "Time Frame": "Wave 2" ``` -```json -[ - { - "date": "2020" - } -] +```yaml +- "Date": "2020" ``` -### 20. Universe + +--- + + +### Universe **Description:** The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A @@ -1249,41 +1287,45 @@ The textual description should not simply restate the time period in words. For **ICPSR Input Guidance:** Universe is distinct from Sampling as it describes the population the study seeks to analyze, while Sampling describes how the researchers selected participants among that population. Universe should not contain information about methodology, only general information about the target population. -**Examples:** +**Examples:** -```json +```text "All households in the United States with phones." ``` -```json +```text "Part 1: Thirty cities in Massachusetts during 1980-1986. Parts 2-4: All residents in Massachusetts during 1986." ``` -```json +```text "Individuals self-identified as transgender, trans, genderqueer, non-binary, or other identities on the transgender identity spectrum aged 18 and older residing in the fifty U.S. states, the District of Columbia, American Samoa, Guam, Puerto Rico, and U.S. military bases overseas." ``` -```json +```text "Jihadists from the United States and Canada, along with Incels from Germany, Canada, the United States, and United Kingdom." ``` -```json +```text "All publicly funded medical examiner and coroner offices." ``` -```json +```text "Uncertified ballots for the 2000 United States presidential election in Florida." ``` -### 21. Data Type + +--- + + +### Data Type **Description:** The types of data included in the data collection. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** Local ICPSR controlled vocabulary. See below for terms and definitions: @@ -1306,146 +1348,154 @@ The textual description should not simply restate the time period in words. For | text | Written work, readable by a machine or human. | | video: film, animation, etc. | Moving image with, or without sound recorded either in analog or digital form. | -**Examples:** +**Examples:** -```json -[ - "administrative records data" -] +```text +"administrative records data" ``` -```json -[ - "census/enumeration data", - "survey data", - "video: film, animation, etc." -] +```text +"census/enumeration data" +"survey data" +"video: film, animation, etc." ``` -### 22. Collection Note + +--- + + +### Collection Note **Description:** Important details about the data collection (like unique authoring, discrepencies, or processing information) that can't be recorded in other metadata elements. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Collection Notes should include any information that does not fit anywhere else in the metadata, such as: information about unique aspects of the way the data was processed, discrepancies between the metadata and documentation files, information about the research team, or series-specific notes. -**Examples:** +**Examples:** -```json -[ - "Exchange rates are expressed in United States dollars per national currency unit or vice versa, and two rates are given for the special drawing right (SDR) value of the national currency unit." -] +```text +"Exchange rates are expressed in United States dollars per national currency unit or vice versa, and two rates are given for the special drawing right (SDR) value of the national currency unit." ``` -```json -[ - "Percentage distributions provided in the codebook were generated using full weights, which are not available on the public use files. Therefore, these results cannot be replicated using the public use files. The differences between results produced using the full weights and those produced using the sampling weights available on the public use files are estimated to be below 1 percent." -] +```text +"Percentage distributions provided in the codebook were generated using full weights, which are not available on the public use files. Therefore, these results cannot be replicated using the public use files. The differences between results produced using the full weights and those produced using the sampling weights available on the public use files are estimated to be below 1 percent." ``` -```json -[ - "Information on the Index of Consumer Sentiment, the Index of Current Economic Conditions, and the Index of Consumer Expectations and how they were created can be found in the P.I. Codebook.", - "Additional information on the Survey of Consumers can be found by visiting the Survey of Consumers Website." -] +```text +"Information on the Index of Consumer Sentiment, the Index of Current Economic Conditions, and the Index of Consumer Expectations and how they were created can be found in the P.I. Codebook." +"Additional information on the Survey of Consumers can be found by visiting the Survey of Consumers Website." ``` -```json -[ - "At PI request, dataset 1 should be attributed to Anura P. Jayasumana while datasets 2-6 should be attributed to Jytte Klausen. Please refer to the PI user guide for additional information." -] +```text +"At PI request, dataset 1 should be attributed to Anura P. Jayasumana while datasets 2-6 should be attributed to Jytte Klausen. Please refer to the PI user guide for additional information." ``` -### 23. Study Purpose + +--- + + +### Study Purpose **Description:** The study's main goals and associated research questions. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** The Study Purpose provides more specific information than the Summary element, including the data collection's objectives, intended achievements, and lists of questions it sought to answer. This element can also include historical or background information about the research project. As with the Summary, the text should be written in third person and avoid any commentary on the data collection's outcomes. -**Examples:** +**Examples:** -```json +```text "The purpose of this study is to advance understanding of the barriers and enablers associated with colorectal cancer (CRC) screening among Somali men ages 50-74 in Minnesota." ``` -```json +```text "The purpose of the study's qualitative phase is to explore veterans' experiences by identifying factors that they believe caused or contributed to their contact with the criminal justice system." ``` -```json +```text "The purpose of the study was to explore the impact of interventions by Sexual Assault Nurse Examiners/Sexual Assault Response Teams (SANE/SART) on the judicial process. The goal of this study was to test the efficacy of SANE/SART programs as a tool in the criminal justice system. The American Prosecutors Research Institute and Boston College tested the hypotheses that SANE/SART exams increase arrest and prosecution rates. In testing this hypothesis, the project team sought to answer five primary research questions: (1) Is the arrest rate higher in cases where a SANE/SART exam is performed as compared with cases in which no exam is performed?, (2) Is the indictment/charging rate higher in such cases?, (3) Are guilty pleas more likely to be entered in such cases, and are pleas likely to be to the existing charge or to a lesser charge?, (4) Is the conviction rate higher in such cases?, and (5) Is the sentence more severe in such cases? In addition, the project team examined the participation of victims in the criminal justice process and the types of services that were offered them. As a large portion of SANE/SART programs focus on understanding victims' reactions to sexual assault and ensuring proper treatment to minimize the chance of further trauma, a central hypothesis to be tested was that improved case outcomes may be a result of increased participation by the victim in the identification, apprehension, and prosecution of the perpetrator. Moreover, the level of services offered and provided to victims, particularly those related to prosecution would likely affect case outcomes as well. Both the victim's participation in the criminal justice system and specifics of SANE/SART services, including evidence collection, were considered in determining the true impact of SANE/SART interventions on case outcomes." ``` -### 24. Study Design + +--- + + +### Study Design **Description:** The procedures used to contact participants and gather data. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** The Study Design provides more detailed information than the Summary, including how surveys were prepared and administered, how interviews were conducted, or how the data were obtained and compiled, as well as information about deadlines and follow-ups to respondents. +**Usage Notes:** The Study Design provides more detailed information than the Summary, including how surveys were prepared and administered, how interviews were conducted, or how the data were obtained and compiled, as well as information about deadlines and follow-ups to respondents. **ICPSR Input Guidance:** It is acceptable to summarize information contained in study documentation and point users to that study documentation for more details. If the Summary already contains text that would be appropriate in Study Design, it is acceptable to duplicate that text. -**Example:** +**Examples:** -```json +```text "Data on organizational culture in each of the 12 courts (Part 1) were obtained by administering the Court Culture Assessment Instrument (CCAI) to all judges with a felony criminal court docket and to all senior court administrators. A total of 224 respondents completed the questionnaire. The CCAI was used to assess five key dimensions of current court culture orientation: (1) dominant case management style, (2) judicial and court staff relations, (3) change management, (4) courthouse leadership, and (5) internal organization. The determination of what culture judges and court administrators desired to establish in the near future was also obtained through the application of the same instrument (CACI) as practitioners were asked to indicate the type of culture in each work area (or content dimension) they would like to see in their court in the next five years. Additionally, surveys were conducted of prosecuting attorneys (Part 2) and public defender attorneys (Part 3) to gauge their views on how well the courts in which they practice achieve the goals of access, fairness, and managerial effectiveness. Every prosecutor and public defender with two years or more experience in representing the state or criminal defendants in felony cases was asked to complete a questionnaire probing their thoughts on how well their court acted to promote access to records through availability and staff cooperation, treating litigants, witnesses, jurors and others fairly, and demonstrating concern for the rights and interests of others in the criminal trial process, including attorney and victims. A total of 334 prosecuting attorneys and 260 public defense attorneys completed the 46-item trial court process survey." ``` -### 25. Variable Description + +--- + + +### Variable Description **Description:** Significant variables (particularly demographic variables) in the data files. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** The Variable Description provides more detailed information than the Summary, including a review of variables that are important for users to know about. The codebook, setup files, and variable groups are appropriate sources of information for Variable Description. -**Examples:** +**Examples:** -```json +```text "The data includes variables about participants' and their parents' moods, interviewer observations, families' activities, families' health history, participants' school records, and parents' substance use. Demographic variables include race, religion, annual household income, and the participants' parents' employment statuses." ``` -```json +```text "The LGBTQ Hate Crimes Interviews dataset contains more in-depth information, including victim demographic information, substance abuse history, information on whether the victim is open about their LGBTQ identification, the victim's job status, and information about how the victim reacted to the crime, such as whether or not they reported the crime to the police and their level of cooperation with the police and prosecution." ``` -### 26. Sampling + +--- + + +### Sampling **Description:** The methods used to select the subset of the population that data are to be collected from (e.g., simple, systematic, stratified). -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A @@ -1453,48 +1503,42 @@ The textual description should not simply restate the time period in words. For **ICPSR Input Guidance:** Sampling is distinct from Universe as it describes the methods the researcher used to select or recruit participants among the target population, while Universe describes the whole population the researchers sought to analyze. If no information about Sampling methodology is available, it is not appropriate to simply restate the Universe. -**Examples:** +**Examples:** -```json -[ - "National sample of telephone numbers from cell (RDD) sampling frame." -] +```text +"National sample of telephone numbers from cell (RDD) sampling frame." ``` -```json -[ - "The probability sample selected to represent the universe consists of approximately 71,000 households." -] +```text +"The probability sample selected to represent the universe consists of approximately 71,000 households." ``` -```json -[ - "The data collection is a pooled cross-sectional time-series of bank robberies in 50 states over a period of 6 years (1970-1975), resulting in 300 observations." -] +```text +"The data collection is a pooled cross-sectional time-series of bank robberies in 50 states over a period of 6 years (1970-1975), resulting in 300 observations." ``` -```json -[ - "Three target groups were identified: lawyers 36 years of age and above who were members of the American Bar Association (ABA), all the remaining members of the ABA excluding law students, and all lawyers in the nonmember files kept by the ABA. A systematic random probability sample was drawn to represent each of the three groups. The group of young lawyers was oversampled." -] +```text +"Three target groups were identified: lawyers 36 years of age and above who were members of the American Bar Association (ABA), all the remaining members of the ABA excluding law students, and all lawyers in the nonmember files kept by the ABA. A systematic random probability sample was drawn to represent each of the three groups. The group of young lawyers was oversampled." ``` -```json -[ - "The original National Longitudinal Survey of Youth Children and Young Adults 1979 (NLSY79) was a multi-stage, stratified random national sample. Sampling weights are available in the public-use datasets to adjust for minority oversamples and year-to-year attrition. There are mother and child specific weights. Primary Sampling Units (PSUs) were counties and independent cities. PSUs were stratified prior to sampling based on 9 Census divisions and 2 urban/rural classes.", - "The initial Panel Study of Income Dynamics (PSID) combined two independent samples: a cross-sectional, national sample (based on stratified multistage selection of the civilian noninstitutional population of the U.S.) and a national sample of low-income families. The cross-section sample was an equal probability sample of households in the 48 coterminous states designed to yield about 3,000 completed interviews. The second sample was selected from the Census Bureau's Survey of Economic Opportunity (SEO) using unequal selection probabilities. " -] +```text +"The original National Longitudinal Survey of Youth Children and Young Adults 1979 (NLSY79) was a multi-stage, stratified random national sample. Sampling weights are available in the public-use datasets to adjust for minority oversamples and year-to-year attrition. There are mother and child specific weights. Primary Sampling Units (PSUs) were counties and independent cities. PSUs were stratified prior to sampling based on 9 Census divisions and 2 urban/rural classes." +"The initial Panel Study of Income Dynamics (PSID) combined two independent samples: a cross-sectional, national sample (based on stratified multistage selection of the civilian noninstitutional population of the U.S.) and a national sample of low-income families. The cross-section sample was an equal probability sample of households in the 48 coterminous states designed to yield about 3,000 completed interviews. The second sample was selected from the Census Bureau's Survey of Economic Opportunity (SEO) using unequal selection probabilities. " ``` -### 27. Time Method + +--- + + +### Time Method **Description:** The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** [DDI Controlled Vocabulary for Time Method](https://vocabularies.cessda.eu/vocabulary/TimeMethod). See below for terms and definitions: @@ -1512,65 +1556,63 @@ The textual description should not simply restate the time period in words. For | Time Series: Continuous | Measurements are taken at every instant in time. Examples: lie detectors, electrocardiograms, etc. | | Time Series: Discrete | Measurements are taken at (usually regularly) spaced intervals. Examples: macroeconomics (weekly share prices, monthly profits, sales); meteorology (hourly temperature); measurements of individuals (blood pressure, weight, height); sociology (crime figures, employment figures), etc. | -**Examples:** +**Examples:** -```json -[ - "Cross-sectional" -] +```text +"Cross-sectional" ``` -```json -[ - "Longitudinal: Cohort / Event-based", - "Time Series" -] +```text +"Longitudinal: Cohort / Event-based" +"Time Series" ``` -### 28. Data Source + +--- + + +### Data Source **Description:** The source of the data, when that source is external to the data collection and can be independently cited. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Data Source includes such source entities as books, journal articles, administrative records, agency-sponsored surveys, or machine-readable files. Each source includes at minimum the title, author, publication year, and journal (if applicable). Any citation format is accepted. -**Examples:** +**Examples:** -```json -[ - "'Voting Scores.' Congressional Quarterly Almanac 33 (1977), 487-498" -] +```text +"'Voting Scores.' Congressional Quarterly Almanac 33 (1977), 487-498" ``` -```json -[ - "United States Bureau of the Census Economic Surveys, 1998-2000", - "United States Congressional Record, 1989" -] +```text +"United States Bureau of the Census Economic Surveys, 1998-2000" +"United States Congressional Record, 1989" ``` -```json -[ - "Annual Company Organization Survey, 2003" -] +```text +"Annual Company Organization Survey, 2003" ``` -### 29. Collection Mode + +--- + + +### Collection Mode **Description:** The method(s) or procedure(s) used to collect the data. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** Local ICPSR controlled vocabulary. See below for terms and definitions: @@ -1597,30 +1639,30 @@ The textual description should not simply restate the time period in words. For | web-based survey | An interview conducted via the Internet. For example, interviews conducted within online forums or using web-based audio-visual technology that enables the interviewer(s) and interviewee(s) to communicate in real time. | | web scraping | A technique employed to extract large amounts of data from websites whereby the data is extracted and saved to a local file or to a database.| -**Examples:** +**Examples:** -```json -[ - "audio computer-assisted self interview (ACASI)" -] +```text +"audio computer-assisted self interview (ACASI)" ``` -```json -[ - "computer-assisted self interview (CASI)", - "face-to-face interview" -] +```text +"computer-assisted self interview (CASI)" +"face-to-face interview" ``` -### 30. Extent of Processing + +--- + + +### Extent of Processing **Description:** Processing activities and checks performed on the data collection by ICPSR curation staff. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** Local ICPSR controlled vocabulary. See below for terms and definitions: @@ -1635,539 +1677,555 @@ The textual description should not simply restate the time period in words. For **ICPSR Input Guidance:** This element is displayed to end-users in version history. -**Examples:** +**Examples:** -```json -[ - "Created variable labels and/or value labels.", - "Standardized missing values.", - "Checked for undocumented or out-of-range codes." -] +```text +"Created variable labels and/or value labels." +"Standardized missing values." +"Checked for undocumented or out-of-range codes." ``` -```json -[ - "Created online analysis version with question text." -] +```text +"Created online analysis version with question text." ``` -### 31. Weight + +--- + + +### Weight **Description:** The weight variables and the criteria for using them in data analysis or other information about how the data are weighted if no weight variables are present. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Weight includes any information about weighting variables in the data, as well as any other weight information provided by the Principal Investigator. If a weighting formula or coefficient was developed, provide this formula, define its elements, and indicate how the formula is applied to the data. It is acceptable to summarize information contained in documentation and refer users to that documentation for more information. -**Examples:** +**Examples:** -```json +```text "A weight variable with two implied decimal places has been included and must be used in any analysis." ``` -```json +```text "Both the TransPop and Cisgender datasets have the same variable named WEIGHT as the weighting variable. The combination datasets have a set of three weight variables (WEIGHT_TRANSPOP, WEIGHT_CISGENDER, WEIGHT_CISGENDER_TRANSPOP). The results will be representative of the sample when the weight is applied. Pages 41 and 42 of the user guide contain instructions that detail how to apply the final sample weight using Stata or SPSS." ``` -```json +```text "The 1996 NES dataset includes two final person-level analysis weights which incorporate sampling, nonresponse, and post-stratification factors. One weight (variable #4) is for longitudinal micro-level analysis using the 1996 NES Panel. The other weight (variable #3) is for analysis of the 1996 NES combined sample (Panel component cases plus Cross-section supplement cases). In addition, a Time Series Weight (variable #5) which corrects for Panel attrition was constructed. This weight should be used in analyses which compare the 1996 NES to earlier unweighted National Election Study data collections." ``` -### 32. Response Rates + +--- + + +### Response Rates **Description:** The percentage of respondents in the sample who participated in the data collection. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Only applicable if the data were collected with a survey instrument and the response rates are provided. -**Examples:** +**Examples:** -```json +```text "The overall response rate for this survey was 20.22%; 72.6% for existing panelists and 10.4% for new panelists, using AAPOR Response Rate 1." ``` -```json +```text "The response rate for the pre-election interview was 55.8 percent (66.5 percent for the Panel and 35.2 percent for the Fresh Cross). The response rate for the post-election interview was 89.1 (90.1 percent for the Panel and 85.2 percent for the Fresh Cross)." ``` -```json +```text "Not applicable." ``` -### 33. Scale + +--- + + +### Scale **Description:** Any commonly known scales used to collect data for the data collection (e.g., MMPI, CPI, the Census Occupational Codes, etc.). -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** Include common scales that can be readily identified from the data, documentation, or other related materials. ICPSR curators are not expected to infer or research scales that are not explicitly indicated. The scales can be cited either as a list or described in full sentences. If the questionnaire used has a finite list of responses (e.g., 'Always, Sometimes, Rarely, Never' or Strongly Agree, Agree, Disagree, Strongly Disagree'), it is acceptable for this element to note 'A Likert-type scale was used,' or 'Several Likert-type scales were used.' However, it is not required to note Likart-type scales in situations where only such scales were used, given their ubiquity. +**Usage Notes:** Include common scales that can be readily identified from the data, documentation, or other related materials. ICPSR curators are not expected to infer or research scales that are not explicitly indicated. The scales can be cited either as a list or described in full sentences. If the questionnaire used has a finite list of responses (e.g., 'Always, Sometimes, Rarely, Never' or Strongly Agree, Agree, Disagree, Strongly Disagree'), it is acceptable for this element to note 'A Likert-type scale was used,' or 'Several Likert-type scales were used.' However, it is not required to note Likart-type scales in situations where only such scales were used, given their ubiquity. -**Examples:** +**Examples:** -```json -[ - "The baseline data collection included one scale - the CES-D index for maternal depression [Cole, J. C., Rabin, A. S., Smith, T. L., and Kaufman, A. S. (2004). Development and validation of a Rasch-derived CES-D short form. Psychological assessment, 16(4), 360]. All scales used for outcomes at ages 1 through 3 are listed in Appendix Tables 1 and 2 in the User Guide. Please refer to the User Guide and P.I. Codebook, available under the 'Data and Documentation' tab, for details." -] +```text +"The baseline data collection included one scale - the CES-D index for maternal depression [Cole, J. C., Rabin, A. S., Smith, T. L., and Kaufman, A. S. (2004). Development and validation of a Rasch-derived CES-D short form. Psychological assessment, 16(4), 360]. All scales used for outcomes at ages 1 through 3 are listed in Appendix Tables 1 and 2 in the User Guide. Please refer to the User Guide and P.I. Codebook, available under the 'Data and Documentation' tab, for details." ``` -```json -[ - "Squires, J., Bricker, D. D., and Twombly, E. (2009). Ages and stages questionnaires. Baltimore, MD: Paul H. Brookes.", - "Briggs-Gowan, M. J., Carter, A. S., Irwin, J. R., Wachtel, K., and Cicchetti, D. V. (2004). The Brief Infant-Toddler Social and Emotional Assessment: screening for social-emotional problems and delays in competence. Journal of pediatric psychology, 29(2), 143-155.", - "Yu, L., Buysse, D. J., Germain, A., Moul, D. E., Stover, A., Dodds, N. E., ... and Pilkonis, P. A. (2012). Development of short forms from the PROMIS sleep disturbance and sleep-related impairment item banks. Behavioral sleep medicine, 10(1), 6-24." -] +```text +"Squires, J., Bricker, D. D., and Twombly, E. (2009). Ages and stages questionnaires. Baltimore, MD: Paul H. Brookes." +"Briggs-Gowan, M. J., Carter, A. S., Irwin, J. R., Wachtel, K., and Cicchetti, D. V. (2004). The Brief Infant-Toddler Social and Emotional Assessment: screening for social-emotional problems and delays in competence. Journal of pediatric psychology, 29(2), 143-155." +"Yu, L., Buysse, D. J., Germain, A., Moul, D. E., Stover, A., Dodds, N. E., ... and Pilkonis, P. A. (2012). Development of short forms from the PROMIS sleep disturbance and sleep-related impairment item banks. Behavioral sleep medicine, 10(1), 6-24." ``` -### 34. Unit of Observation + +--- + + +### Unit of Observation **Description:** The object(s) of analysis for the data collection, such as an organization, individual, or household. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Use a brief phrase, for example: 'Individual,' 'Family,' 'Household,' or 'Organization'; when possible, conform to the [DDI Controlled Vocabulary for Analysis Unit](https://vocabularies.cessda.eu/vocabulary/AnalysisUnit). -**Examples:** +**Examples:** -```json -[ - "Organization" -] +```text +"Organization" ``` -```json -[ - "Individual, Household" -] +```text +"Individual, Household" ``` -```json -[ - "Family" -] +```text +"Family" ``` -### 35. Smallest Geographic Unit + +--- + + +### Smallest Geographic Unit **Description:** The smallest geographic unit (e.g., state or census tract) used in the dataset. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Usage Notes:** Geographic Unit is intended to represent specific, known geography -- e.g., county, census district, FIPS code, electoral district, and any other conveyor of specific geography that is represented by a variable. +**Usage Notes:** Geographic Unit is intended to represent specific, known geography – e.g., county, census district, FIPS code, electoral district, and any other conveyor of specific geography that is represented by a variable. -If the data do not include a geographic variable by which the data can be analyzed, this element is not indicated. If all the cases are from a single state, but the cases are not subdivided geographically within that state, then 'state' is not indicated. +If the data do not include a geographic variable by which the data can be analyzed, this element is not indicated. If all the cases are from a single state, but the cases are not subdivided geographically within that state, then 'state' is not indicated. -This element is only meant to convey specific, known, geography. If there is a variable indicating which testing site a survey was taken at, but the locations of the testing sites were masked by the PI, this element is likely not indicated. +This element is only meant to convey specific, known, geography. If there is a variable indicating which testing site a survey was taken at, but the locations of the testing sites were masked by the PI, this element is likely not indicated. **ICPSR Input Guidance:** The following is a non-exhaustive list of potential entries: census tract, city, congressional district, Core-Based Statistical Area (CBSA), country, county, Federal Court District, FIPS code, jurisdiction, neighborhood, school district, state, ZIP code. -**Examples:** +**Examples:** -```json +```text "state" ``` -```json +```text "Census tract" ``` -```json +```text "precinct" ``` -### 36. Restrictions + +--- + + +### Restrictions **Description:** Rules about how the data collection can be accessed or used. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Restrictions informs users that access to certain variables in a collection may be limited, and that they should contact ICPSR directly to inquire about accessing them. -**Example:** +**Examples:** -```json +```text "These data may not be used for any purpose other than statistical reporting and analysis. Use of these data to learn the identity of any person or establishment is strictly prohibited. To protect respondent privacy, certain files within this data collection are restricted from general dissemination. To obtain these files, researchers must agree to the terms and conditions of a Restricted Data Use Agreement in accordance with existing ICPSR servicing policies." ``` -### 37. Membership Required + +--- + + +### Membership Required **Description:** The availability of the data collection in terms of ICPSR membership. Members-only data may only be downloaded by affiliates of ICPSR member institutions who contribute funding to support the data. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Boolean **Controlled Vocabulary:** N/A **Usage Notes:** True indicates the data are only available to members; false indicates that the data are available to all users. Additional access restrictions (i.e., due to sensitive data or disclosure risks) may still apply. -**Examples:** +**Examples:** -```json +```text "True" ``` -```json +```text "False" ``` -### 38. Restricted Access + +--- + + +### Restricted Access **Description:** General indication of any access restrictions associated with the data collection. More detailed information is provided in the Restrictions element. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Boolean **Controlled Vocabulary:** N/A **Usage Notes:** True indicates that an access restriction is associated with the data collection; false indicates no access restrictions are present. Additional membership requirements may still apply. -**Examples:** +**Examples:** -```json +```text "True" ``` -```json +```text "False" ``` -### 39. Changes to Collection + +--- + + +### Changes to Collection **Description:** A record of how the data collection has changed over time. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields **Controlled Vocabulary:** N/A **Usage Notes:** Textual changes are recorded only when data or documentation files are updated or added to the data collection (and the Version number is incremented). -#### 39.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| ------------------------------------------ | --------- | ----------- | --------------- | ------------------------------------------------------------------------------ | -| [Date](#changes_to_collection_items_date ) | No | No | Text | The date on which an update occurred. ICPSR automatically generates this date. | -| [Note](#changes_to_collection_items_note ) | No | No | Text | An explanation of the nature of the update. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Date](#changes-to-collection_date) | No | No | Text | The date on which an update occurred. ICPSR automatically generates this date. | +| [Note](#changes-to-collection_note) | No | No | Text | An explanation of the nature of the update. | -##### 39.1.1. Date + +##### Date **Description:** The date on which an update occurred. ICPSR automatically generates this date. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text (formatted as a date) +**Accepted Values:** Text -**Examples:** +**Examples:** -```json +```text "2006-03-30" ``` -```json +```text "2019-05-05" ``` -##### 39.1.2. Note + +##### Note **Description:** An explanation of the nature of the update. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text -**Examples:** +**Examples:** -```json +```text "File CB3025.ALL.PDF was removed from any previous datasets and flagged as a study-level file, so that it will accompany all downloads." ``` -```json +```text "The data producer provided additional data files." ``` -```json +```text "SAS and SPSS setup files were created." ``` -```json +```text "The codebook descriptions of variables TANSUP, EMOSUP, and SOCSUP were corrected." ``` -###### Complete Changes to Collection Examples (with Subfields): -```json -[ - { - "date": "2003-09-10", - "note": "A variable specifying the date of interview has been added to the collection." - }, - { - "date": "2003-12-09", - "note": "The codebook descriptions of variables TANSUP, EMOSUP, and SOCSUP were corrected." - } -] +#### Complete Changes to Collection Examples (with Subfields): + +```yaml +- "Date": "2003-09-10" + "Note": "A variable specifying the date of interview has been added to the collection." + +- "Date": "2003-12-09" + "Note": "The codebook descriptions of variables TANSUP, EMOSUP, and SOCSUP were\ + \ corrected." ``` -### 40. Series + +--- + + +### Series **Description:** A named collection of related studies. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** [ICPSR Series](https://www.icpsr.umich.edu/web/ICPSR/search/series) **Usage Notes:** Typically the studies in an ICPSR series are produced by the same group of investigators, and either explore different facets of the same topic, or repeat the same investigation over time. Each series name is given in title case (all major words are capitalized, while minor words are lowercased) and ends with the word 'Series'. -**Examples:** +**Examples:** -```json -[ - "American National Election Study (ANES) Series" -] +```text +"American National Election Study (ANES) Series" ``` -```json -[ - "Census of Population and Housing, 1990 [United States] Series" -] +```text +"Census of Population and Housing, 1990 [United States] Series" ``` -```json -[ - "National Black Election Study Series" -] +```text +"National Black Election Study Series" ``` -```json -[ - "Study of Women's Health Across the Nation (SWAN) Series" -] +```text +"Study of Women's Health Across the Nation (SWAN) Series" ``` -### 41. Classification + +--- + + +### Classification **Description:** Topics used to organize data collections and help users explore the ICPSR catalog. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** [ICPSR Topic Classifications](https://www.icpsr.umich.edu/web/pages/ICPSR/access/subject.html) **ICPSR Input Guidance:** When there are multiple subclassifications, the smallest (most detailed) one is chosen to represent the data collection. Each data collection must have at least one ICPSR classification, as well as a classification from the collection's home archive. Classifications can also be used to cross-list a study among multiple archives. Curators should choose the topical classifications that best match the study's focus. -**Examples:** +**Examples:** -```json -[ - "I.A.2. Census Enumerations: Historical and Contemporary Population Characteristics, United States, American Housing Survey Series" -] +```text +"I.A.2. Census Enumerations: Historical and Contemporary Population Characteristics, United States, American Housing Survey Series" ``` -```json -[ - "XVII.C.1. Social Institutions and Behavior, Socialization, Students, and Youth, United States" -] +```text +"XVII.C.1. Social Institutions and Behavior, Socialization, Students, and Youth, United States" ``` -### 42. Filesets + +--- + + +### Filesets **Description:** The grouping of files in the data collection. -**Required**: No +**Required:** No -**Repeatable**: Yes +**Repeatable:** Yes -**Accepted Values**: Multi-part element; see subfield definitions for more information. +**Accepted Values:** Multi-part element; see subfields **Controlled Vocabulary:** N/A -**Usage Notes:** Filesets are used at ICPSR to make a convenient package for description, discovery, preservation and dissemination -- a package that is smaller than the data collection but larger than the individual file. A fileset typically contains a single file of statistical data plus additional files that support the data -- such as setups for statistical software, documentation, and alternative data representations. Every ICPSR data collection with at least one file must have at least one defined Fileset; a data collection may have multiple filesets. Each Fileset has a Number, and may also have a Name and an SDA (Survey Documentation and Analysis) Note. +**Usage Notes:** Filesets are used at ICPSR to make a convenient package for description, discovery, preservation and dissemination – a package that is smaller than the data collection but larger than the individual file. A fileset typically contains a single file of statistical data plus additional files that support the data – such as setups for statistical software, documentation, and alternative data representations. Every ICPSR data collection with at least one file must have at least one defined Fileset; a data collection may have multiple filesets. Each Fileset has a Number, and may also have a Name and an SDA (Survey Documentation and Analysis) Note. -#### 42.1. Subfields: +#### Subfields: -| Property | Required? | Repeatable? | Accepted Values | Description | -| ------------------------------------- | --------- | ----------- | --------------- | --------------------------------------------------------------------------------------------------------- | -| [Number](#filesets_items_number ) | Yes | No | Number | A number that uniquely identifies a 'part' or component file that is associated with the data collection. | -| [Name](#filesets_items_name ) | No | No | Text | A brief title used to distinguish each fileset within a data collection. | -| [SDA Note](#filesets_items_sda_note ) | No | No | Text | Additional information about the fileset for the purpose of helping online analysis users. | +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Number](#filesets_number) | Yes | No | Number | A number that uniquely identifies a 'part' or component file that is associated with the data collection. | +| [Name](#filesets_name) | No | No | Text | A brief title used to distinguish each fileset within a data collection. | +| [SDA Note](#filesets_sda_note) | No | No | Text | Additional information about the fileset for the purpose of helping online analysis users. | -##### 42.1.1. Number + +##### Number **Description:** A number that uniquely identifies a 'part' or component file that is associated with the data collection. -**Required**: Yes +**Required:** Yes -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Number +**Accepted Values:** Number **Usage Notes:** Fileset numbers are typically (but not always) consecutive integers beginning with 1. (In some cases, the number may be drawn from an external resource, such as FIPS state and county codes.) The numbers correspond to the 'part numbers' embedded in ICPSR standard filenames. -**Examples:** +**Examples:** -```json -1 +```text +"1" ``` -```json -2 +```text +"2" ``` -```json -3 +```text +"3" ``` -##### 42.1.2. Name + +##### Name **Description:** A brief title used to distinguish each fileset within a data collection. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A **Usage Notes:** Fileset Names are required for data collections that include multiple Filesets. If a data collection includes only one fileset, a Fileset Name is not included. Fileset Names use title case (all main words are capitalized) and do not begin with articles (a, the) or dates. -**Examples:** +**Examples:** -```json +```text "Each Region, Wealth Summary: Middle Colonies (MIDLCOL)" ``` -```json +```text "Each Region, Wealth Summary: New England (NEWENGL)" ``` -```json +```text "Northbound Public-Use Data" ``` -```json +```text "Northbound Restricted-Use Data" ``` -##### 42.1.3. SDA Note + +##### SDA Note **Description:** Additional information about the fileset for the purpose of helping online analysis users. -**Required**: No +**Required:** No -**Repeatable**: No +**Repeatable:** No -**Accepted Values**: Text +**Accepted Values:** Text **Controlled Vocabulary:** N/A -**Examples:** +**Examples:** -```json +```text "Please note that the AABS provides estimates for 32 states. It also supplies arts participation estimates for 11 metropolitan areas. Users are encouraged to review the Data Collection Notes on the Study Description page for specific states and metropolitan areas." ``` -```json +```text "Please note that the replicate weights are needed to obtain accurate standard error estimates. Users are advised to download the data to use the replicate weights. Users should refer to the study description page or User Guide for further details regarding weights." ``` -###### Complete Filesets Examples (with Subfields): -```json -[ - { - "number": 1 - } -] +#### Complete Filesets Examples (with Subfields): + +```yaml +- "Number": 1 ``` -```json -[ - { - "number": 1, - "name": "Northbound Public-Use Data" - }, - { - "number": 2, - "name": "Northbound Restricted-Use Data" - } -] +```yaml +- "Number": 1 + "Name": "Northbound Public-Use Data" + +- "Number": 2 + "Name": "Northbound Restricted-Use Data" ``` -```json -[ - { - "number": 1, - "name": "Original File" - }, - { - "number": 2, - "name": "Replicate Weight File", - "sda_note": "Please note that the replicate weights are needed to obtain accurate standard error estimates. Users are advised to download the data to use the replicate weights. Users should refer to the study description page or User Guide for further details regarding weights." - } -] +```yaml +- "Number": 1 + "Name": "Original File" + +- "Number": 2 + "Name": "Replicate Weight File" + "SDA Note": "Please note that the replicate weights are needed to obtain accurate\ + \ standard error estimates. Users are advised to download the data to use the\ + \ replicate weights. Users should refer to the study description page or User\ + \ Guide for further details regarding weights." ``` -## ICPSR Metadata Schema Version History +--- + +## ICPSR Legacy Metadata Schema Version History | Date | Version | Note | |------|---------|------| +| April 14, 2026 | v1.3 | Updated ICPSR input guidance for Geographic Coverage Area. | | April 11, 2025 | v1.2 | Updated field definitions to improve clarity. | | June 28, 2024 | v1.1 | Removed guidance regarding null entries for National Institute of Justice studies. Several fields previously required "None" when otherwise a field would be left blank. Updated internal guidance for 'external source id' and 'funding purpose' elements. Added 'study number' and distributor 'order' elements to address earlier oversights. | -| Oct. 30, 2023 | v1 | Initial release and publication of the ICPSR Metadata Schema. | - +| Oct. 30, 2023 | v1 | Initial release and publication of the legacy ICPSR Metadata Schema. | diff --git a/markdown/icpsr_metadata_api.md b/markdown/icpsr_metadata_api.md index 85cbe51..7dbb2f1 100644 --- a/markdown/icpsr_metadata_api.md +++ b/markdown/icpsr_metadata_api.md @@ -3,7 +3,7 @@ ICPSR has developed a new application programming interface (API) to help researchers and data users: - **Search** data collections by specific metadata fields such as study identifier, subject terms, geographic coverage area, original release date -- and even run more advanced queries. - - **Export** metadata about those collections in widely used formats such as DCAT-US, MARCXML, and Dublin Core, making it easier to share and integrate with other systems. + - **Export** metadata about those collections in widely used formats such as DCAT-US, MARCXML, and Dublin Core, making it easier to share and integrate with other systems. ## Getting Started diff --git a/markdown/icpsr_metadata_schema.md b/markdown/icpsr_metadata_schema.md new file mode 100644 index 0000000..8bbb833 --- /dev/null +++ b/markdown/icpsr_metadata_schema.md @@ -0,0 +1,3630 @@ +# ICPSR Metadata Schema + +Last updated: May 12, 2026 + + +This metadata schema is used to describe data collections at the Inter-university Consortium for Political and Social Research (ICPSR) after 2026. + +These rules and definitions document ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help users – including data depositors and researchers – understand and interpret ICPSR metadata. + +Machine-actionable copies of metadata field definitions are also available in [JSON Schema](https://github.com/ICPSR/metadata/tree/main/rde_schema/property_bank) format. +## Metadata Elements: Overview + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Title](#title) | Yes | No | Text | The official title that describes what the data collection is about, its geographic scope, and the time period it covered. | +| [Alternate Titles](#alternate-titles) | No | Yes | Text | The alternate name(s) or acronym(s) commonly used to refer to the data collection. | +| [Principal Investigators](#principal-investigators) | Yes | Yes | Multi-part element; see subfields | The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization. | +| [Funding Sources](#funding-sources) | No | Yes | Multi-part element; see subfields | The sources of funding that supported the data collection. | +| [Summary](#summary) | Yes | No | Text | A description of the data collection that helps users understand its purpose, substance, and key topics. | +| [ICPSR Subject Terms](#icpsr-subject-terms) | Yes | Yes | Multi-part element; see subfields | A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection. | +| [Journal of Economic Literature (JEL) Classification Codes](#journal-of-economic-literature-(jel)-classification-codes) | No | Yes | Multi-part element; see subfields | Classification codes used to categorize economic research. | +| [Medical Subject Headings (MeSH) Terms](#medical-subject-headings-(mesh)-terms) | No | Yes | Multi-part element; see subfields | Biomedical and health-related terms from the National Library of Medicine that describe the data collection's topics. | +| [Time Periods](#time-periods) | Yes | Yes | Multi-part element; see subfields | The time period(s) to which the data refer, regardless of when the data were collected. | +| [Nationally Representative Sample](#nationally-representative-sample) | No | No | Text | Indicates whether the data collection uses a sampling design intended to represent the demographics, behaviors, and/or characteristics of the entire nation. This typically involves probability-based methods that allow generalization. It does not include convenience samples that appear similar to the nation by chance. | +| [Geographic Coverage Areas](#geographic-coverage-areas) | Yes | Yes | Multi-part element; see subfields | The geographic locations where the data refer or are related. | +| [Smallest Geographic Unit](#smallest-geographic-unit) | No | No | Multi-part element; see subfields | The smallest geographic unit (e.g., state or census tract) used in the dataset. | +| [Study Design](#study-design) | No | No | Text | The procedures used to contact participants and gather data. | +| [Universe](#universe) | No | No | Text | The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer. | +| [Time Methods](#time-methods) | No | Yes | Multi-part element; see subfields | The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends. | +| [Units of Analysis](#units-of-analysis) | No | Yes | Multi-part element; see subfields | The object(s) of analysis for the data collection, such as an organization, individual, or household. | +| [Sampling Procedures](#sampling-procedures) | No | Yes | Text | The type(s) of sample and sample design used to select survey respondents to represent the population. | +| [Sampling Note](#sampling-note) | No | No | Text | Supplemental information about the sampling process that does not fit neatly into the Sampling Procedure field. | +| [Weights](#weights) | No | No | Text | The weight variables and the criteria for using them in data analysis, or other information about how the data are weighted if no weight variables are present. | +| [Response Rates](#response-rates) | No | No | Text | The percentage of respondents in the sample who participated in the data collection. | +| [Data Source Types](#data-source-types) | No | Yes | Multi-part element; see subfields | The source(s) of the data as collected by the Principal Investigators. | +| [External Data Sources](#external-data-sources) | No | Yes | Text | The source of the data, when that source is external to the data collection and can be independently cited. | +| [Collection Modes](#collection-modes) | No | Yes | Multi-part element; see subfields | The method(s) or procedure(s) used to collect the data, such as an interview or experiment. | +| [Collection Dates](#collection-dates) | No | Yes | Multi-part element; see subfields | The date(s) data collection took place. | +| [Variable Description](#variable-description) | No | No | Text | Significant variables (particularly demographic variables) in the data files. | +| [Scales](#scales) | No | No | Text | Any commonly known scales, measures, or inventories used in the data collection. | +| [Data Management Plan](#data-management-plan) | No | No | Text | A link to the data management plan (preferably a persistent identifier such as a DOI). | +| [Preregistration](#preregistration) | No | No | Text | A link to a research plan for the data collection (preferably a persistent identifier such as a DOI). | +| [Software Applications](#software-applications) | No | Yes | Multi-part element; see subfields | Software used by the principal investigator(s) to collect or analyze data, required to understand how the data were obtained or to reproduce results. | +| [General Data Formats](#general-data-formats) | No | Yes | Multi-part element; see subfields | The file format types present in the data collection. | +| [Notes](#notes) | No | Yes | Text | Important details about the data collection (like unique authoring, discrepancies, or processing information) that can't be recorded in other metadata elements. | +| [Manuscript Number](#manuscript-number) | No | No | Text | A unique identifier that associates the data collection with a manuscript submitted to a journal. | +| [ADA Accessibility](#ada-accessibility) | No | No | Multi-part element; see subfields | Indicates whether the data collection is ADA accessible, conforming to WCAG 2.1 AA standards, or qualifies for the ADA archival exception. | +| [License](#license) | No | No | Multi-part element; see subfields | A license governing the data's use. | +| [Version History](#version-history) | No | Yes | Multi-part element; see subfields | A record of how the data collection has changed over time. | +| [Distributors](#distributors) | No | Yes | Multi-part element; see subfields | The organization(s) responsible for distributing the data collection. | +| [Study Number](#study-number) | Yes | No | Number | A unique, numerical value used by ICPSR to identify and track data collections. | +| [Digital Object Identifier (DOI)](#digital-object-identifier-(doi)) | Yes | No | Text | The registered persistent digital object identifier (DOI) associated with the data collection. | +| [Citation](#citation) | No | No | Text | The official way to reference the data collection in writing. | +| [Person](#person) | No | No | Multi-part element; see subfields | A person associated with an ICPSR data collection or service. | +| [Organization](#organization) | No | No | Multi-part element; see subfields | An organization associated with an ICPSR data collection or service. | + +--- + +## Key for ICPSR Metadata Schema Entries + +Full information for each ICPSR study metadata element includes the following fields: + +- **Description:** A short description of the metadata element and the information it is intended to convey. +- **Required:** Indicates whether the metadata element is mandatory ("Yes") or optional ("No"). Required elements must include at least one value. +- **Repeatable:** Indicates whether the metadata element may be repeated ("Yes") or if it may only occur once ("No"). +- **Accepted values:** The type of values that may be used with the metadata element; options include text (with additional requirements, such as date formatting, noted when present) and numbers. Multi-part metadata elements have accepted value information provided in entries for individual subelements. +- **Usage Notes:** Additional information about the nature, scope, and conventions for values that may be added to the metadata element. +- **Examples:** Examples of valid values for the metadata element. + + +--- +## Metadata Elements: Detailed Information + + +### Title + +**Description:** The official title that describes what the data collection is about, its geographic scope, and the time period it covered. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The Title includes three essential parts: the title proper, the geography, and the time period. + +Title Proper: + + * The title proper is a descriptive string that captures what the data collection contains. + + * The title proper uses title case: all major words are capitalized, while minor words are lowercased. + + * For new studies, ICPSR starts with the title proper provided by the data depositor. Most title propers are straightforward about their contents, such as the 'American Community Survey' or the 'Census of Law Enforcement Training Academies.' Some title propers include a more branded description, such as 'Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project or Contents' and 'Contexts of Cyberbullying: An Epidemiologic Study using Electronic Detection and Social Network Analysis.' + + * For updated studies, ICPSR uses the existing title in production, making changes as necessary to add new years or additional geographical locations. For studies that are part of an ICPSR series, titles remain consistent with the previous series studies. + +Geography: + + * All titles include the data collection's geography. If the geography is already included in the title proper, it is not repeated. + + * Cities are paired with state or province names that are spelled out (e.g., Portland, Oregon), unless the city names are unique or well-known. + + * Studies with more than four geographic locations typically are summarized using, for example, '5 countries,' '8 German cities,' '20 U.S. states' instead of listing all locations. In the latter case, 'U.S.' is used rather than 'United States' or 'American'. + + * Descriptors that do not have a distinct geographic area, such as 'communities' or 'regions', are not included in titles. + + * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. + + * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has "National" in the title, or a similar word specific to that country. + +Time Period: + + * All titles include the data collection's time period, which reflects the time period that the data collection covers and should match the Time Period. For example, in the 'Uganda Elite Study, 1964-1968', it is assumed that the Ugandans were surveyed about events in 1964-1968, even if the actual data collection might not have taken place until later. + + * If the time period is already included in the title proper, it is not repeated. + + * For most studies, a single year or range of years is acceptable. Years are written as four digits, including when used in a range (e.g., '1999', '2001-2003', or '1999, 2010, 2015'). + + * Months are included only when part of ICPSR series that have multiple releases, which are otherwise identical, each year. In these cases, months are spelled out (e.g., 'September 2020' instead of '9/2020' or 'Sept. 2020'). + +**Examples:** + +```text +"Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project, Kansas City, Missouri, 2014-2017" +``` + +```text +"Health and Relationships Project, United States, 2014-2015" +``` + +```text +"Targeted Interventions to Prevent Chronic Low Back Pain in High Risk Patients: A Multi-Site Pragmatic Randomized Controlled Trial (TARGET Trial), 4 U.S. cities, 2016-2019" +``` + +```text +"Aid Like A Paycheck (ALAP), Texas and California, 2014-2017" +``` + +```text +"COVID-19 Disruptions Disproportionately Affect Female Academics, Global, 2020" +``` + + +--- + + +### Alternate Titles + +**Description:** The alternate name(s) or acronym(s) commonly used to refer to the data collection. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Usage Notes:** Alternate Title often takes the form of a shortened (by abbreviation or acronym) version of the official title. + +**Examples:** + +```text +"Add Health Parent Study" +``` + +```text +"FACES 2009" +``` + +```text +"Survey of Consumers" +``` + +```text +"Eurobarometer 85.2" +``` + + +--- + + +### Principal Investigators + +**Description:** The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization. + +**Required:** Yes + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** List individuals and organizations that are chiefly responsible for the study across its entire life cycle or made significant intellectual contributions to the research. + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Person](#principal-investigators_person) | Conditional | No | Multi-part element; see subfields | Name and other details about the principal investigator, if it is an individual person. | +| [Organization](#principal-investigators_organization) | Conditional | No | Multi-part element; see subfields | Name and other details about the principal investigator, if it is an organization. | +| [Order](#principal-investigators_order) | Yes | No | Number | The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI. | + + +##### Person + +**Description:** Name and other details about the principal investigator, if it is an individual person. + +**Required:** Conditional (must include either Person or Organization) + +**Repeatable:** No + +**Accepted Values:** Multi-part element; for more information, see the [Person](#person) field + +**Usage Notes:** When entering the name of a principal investigator who is a person: + + * Enter a specific and unique name, for example, by including full names and middle initials where appropriate. + * Follow commonly accepted, language-appropriate practices for capitalization and punctuation. + * Within the bounds of these first two principles, follow the PI’s precedent for how their name appears in print. + +To determine the preferred form of name to appear in ICPSR’s metadata catalog, consult the following authority sources, in this order. + * ICPSR's metadata catalog. If the PI has published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The PI’s curriculum vitae published on an institutional website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * The PI’s [Open Researcher and Contributor Identifier](https://orcid.org/) (ORCID) record. + * The PI’s Google Scholar profile. + * The PI’s other published works. + * The PI’s bio on their organization’s website. + +The given (i.e., 'first') name may include the middle name or initial. If the person only uses an inital for the given name, do not include a space between first and middle initials (e.g., 'E.V.'). The family (i.e., 'last') name can include any suffixes (such as 'II' or 'Jr.'). Abbreviations are discouraged (especially 'et al.'). + +Whenever possible, add an ORCID for each principal investigator. + +When entering a principal investigator's affiliation(s): + * Enter the PI's affiliation as it appears in the Research Organization Registry (ROR). + * If the organization doesn't have a ROR ID, enter its full name, avoid acronyms, and do not include departments or colleges. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If other PIs affiliated with this organization have published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The Virtual International Authority File (VIAF). + * Enter a PI's affiliation at the time the research was conducted. If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + * If a PI's affiliation has both English and non-English name forms in ROR or VIAF, select a preferred English language form. + * If a PI's organizational affiliation is not known, use the term 'Unknown' in the PI Organization element. + * If multiple PIs (people) are affiliated with the same organization, include the affiliated organization's name for each person. + * If a PI has multiple affiliations, enter each organization as its own affiliation. + + +##### Organization + +**Description:** Name and other details about the principal investigator, if it is an organization. + +**Required:** Conditional (must include either Person or Organization) + +**Repeatable:** No + +**Accepted Values:** Multi-part element; for more information, see the [Organization](#organization) field + +**Usage Notes:** When entering the name of a principal investigator that is an organization: + + * Whenever possible, enter the organization name as it appears in the [Research Organization Registry](https://ror.org/) (ROR). + * If the principal investigator is a department or subunit of an organization that appears in ROR, but does not have its own ROR ID, enter the organization name as it appears in ROR, followed by a period and the name of the department or subunit. + * If the organization doesn’t have a ROR ID, use its full name and avoid acronyms. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If the PI has published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * Except for principal investigators that are departments or subunits of organizations in ROR, do not prepend the organization's name with its institutional hierarchy. For example, enter "National Institute on Aging," not "United States Department of Health and Human Services. National Institutes of Health. National Institute on Aging." + * If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + + When selecting a ROR ID, choose the most specific applicable ROR (for example, Inter-university Consortium for Political and Social Research, not University of Michigan). + + +##### Order + +**Description:** The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Number + +**Examples:** + +```text +"0" +``` + +```text +"1" +``` + +```text +"2" +``` + +#### Complete Principal Investigators Examples (with Subfields): + +```yaml +- "Person": + "Name": + "Given": "Miner P." + "Family": "Marchbanks III" + "Order": 0 +``` + +```yaml +- "Person": + "Name": + "Given": "Robert J." + "Family": "Shiller" + "Orcid": "https://orcid.org/0009-0006-2316-6486" + "Affiliations": + - "Name": "Yale University" + "Ror": "https://ror.org/03v76x132" + - "Name": "MacroMarkets" + "Order": 0 + +- "Person": + "Name": + "Given": "Claudia" + "Family": "Goldin" + "Orcid": "https://orcid.org/0000-0003-3842-1604" + "Affiliations": + - "Name": "Harvard University" + "Ror": "https://ror.org/03vek6s52" + "Order": 1 + +- "Organization": + "Name": "Bureau of Justice Statistics" + "Ror": "https://ror.org/0006s4z66" + "Order": 2 +``` + + +--- + + +### Funding Sources + +**Description:** The sources of funding that supported the data collection. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Funding Organization](#funding-sources_organization) | Yes | No | Multi-part element; see subfields | Name and other details about the organization that provided the funding. | +| [Funding Awards](#funding-sources_grants) | No | Yes | Multi-part element; see subfields | Identifiers and other details about financial support for the data collection. | +| [Order](#funding-sources_order) | Yes | No | Number | Internal ICPSR field used to determine the order of importance for the funders associated with the data collection. | + + +##### Funding Organization + +**Description:** Name and other details about the organization that provided the funding. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Multi-part element; for more information, see the [Organization](#organization) field + +**Usage Notes:** When entering the name of a funding organization: + + * Whenever possible, enter the organization’s name as it appears in the [Research Organization Registry](https://ror.org/) (ROR). + * If the funding organization is a department or subunit of an organization that appears in ROR, but does not have its own ROR ID, enter the organization name as it appears in ROR, followed by a period and the name of the department or subunit. + * If the organization doesn't have a ROR ID, use its full name and avoid acronyms. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If the organization has funded data collections with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * Except for principal investigators that are departments or subunits of organizations in ROR, do not prepend the organization's name with its institutional hierarchy. For example, enter "National Institute on Aging" instead of "United States Department of Health and Human Services. National Institutes of Health. National Institute on Aging". + * If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + + The Principal Investigator's home institution does not need to be listed as a funding agency unless the PI provides a grant number (or other award information) or makes a specific request. + + +##### Funding Awards + +**Description:** Identifiers and other details about financial support for the data collection. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** Whenever possible, provide a grant number for the funding award. If one exists, you can also provide a URL, preferably a persistent one like a digital object identifier (DOI). + +##### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Funding Identifier](#funding-sources_grants_grant_number) | Yes | No | Text | The unique identifier for the funding (e.g., ABC-0123456). | +| [Funding URL](#funding-sources_grants_grant_uri) | No | No | Text | A unique identifier (URL), preferably a persistent one like a DOI, linking to a landing page with funding information. | + + +###### Funding Identifier + +**Description:** The unique identifier for the funding (e.g., ABC-0123456). + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"SES-1835721" +``` + +```text +"MDR-8550085" +``` + +```text +"40791" +``` + + +###### Funding URL + +**Description:** A unique identifier (URL), preferably a persistent one like a DOI, linking to a landing page with funding information. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://doi.org/10.35802/212242" +``` + + +##### Order + +**Description:** Internal ICPSR field used to determine the order of importance for the funders associated with the data collection. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Number + +**Examples:** + +```text +"0" +``` + +```text +"1" +``` + +```text +"2" +``` + +#### Complete Funding Sources Examples (with Subfields): + +```yaml +- "Funding Organization": + "Name": "Robert Wood Johnson Foundation" + "Ror": "https://ror.org/02ymmdj85" + "Funding Awards": + - "Funding Identifier": "MDR-8550085" + - "Funding Identifier": "MDR-8550204" + "Order": 0 + +- "Funding Organization": + "Name": "Bureau of Justice Statistics" + "Ror": "https://ror.org/0006s4z66" + "Funding Awards": + - "Funding Identifier": "SES-1835721" + "Funding URL": "https://doi.org/10.35802/000000" + "Order": 1 +``` + +```yaml +- "Funding Organization": + "Name": "Acme Foundation" + "Order": 0 +``` + + +--- + + +### Summary + +**Description:** A description of the data collection that helps users understand its purpose, substance, and key topics. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The Summary may include information about the different parts of the data collection not adequately conveyed by the Fileset names or found elsewhere in the metadata. Other important components include a listing of major variables or categories of variables (with examples) as well as an indication of the data collection's unit of analysis (i.e., who or what is being studied: individuals, housing units, courts, criminal acts, etc.). Most often the unit of analysis is the individual; where it is not, it is particularly important to make this clear. + +The Summary is written in the third person and avoids attempting to address issues of how the data might be used, who might be interested in the data, or any evaluative comments about the worth or usefulness of the data collection. The Summary uses past tense when describing the process of collecting the data and present tense when necessary, such as when describing the data (e.g., 'The MIDUS Refresher collection is split into two datasets.'). Numerals are used instead of spelling them out; if a number is spelled out for emphasis, the number is attached in parentheses – e.g. 'Two thousand (2,000)'. + +**Examples:** + +```text +"In 2014, Chicago Public Schools, looking to reduce the possibility of gun violence among school-aged youth, applied for a grant through the National Institute of Justice. CPS was awarded the Comprehensive School Safety Initiative grant and use said grant to establish the 'Connect and Redirect to Respect' program. This program used student social media data to identify and intervene with students thought to be at higher risk for committing violence. At-risk behaviors included brandishing a weapon, instigating conflict online, signaling gang involvement, and threats towards others. Identified at-risk students would be contacted by a member of the CPS Network Safety Team or the Chicago Police Department's Gang School Safety Team, depending on the risk level of the behavior. To evaluate the efficacy of CRR, the University of Chicago Crime Lab compared outcomes for students enrolled in schools that received the program to outcomes for students enrolled in comparison schools, which did not receive the program. 32 schools were selected for the study, with a total of 44,503 students. Demographic variables included age, race, sex, and ethnicity. Misconduct and academic variables included arrest history, in-school suspensions, out-of-school suspensions, GPA, and attendance days." +``` + +```text +"The Health and Relationship Project is a study of both spouses in same-sex and different-sex marriages who were legally married and aged 35 to 65 at the time of data collection (2015). There are two parts of this study: a baseline questionnaire and a daily diary questionnaire completed for 10 consecutive days; both components were completed online and spouses were asked to complete the surveys separately. The baseline questionnaire asks participants about a number of topics related to marriage and health, including stress, health status and health behaviors, relationship quality, and how they have approached health problems in the past. The diary questionnaire asks participants a number of questions about the past 24 hours, including daily stress experiences, social interactions, and health behaviors." +``` + + +--- + + +### ICPSR Subject Terms + +**Description:** A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection. + +**Required:** Yes + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the ICPSR Subject Terms Thesaurus. Source: [https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [ICPSR Subject Term](#icpsr-subject-terms_label) | Yes | No | Text | A human-readable form of the subject term. | +| [ICPSR Subject Term Code](#icpsr-subject-terms_code) | Yes | No | Text | A machine-readable/-actionable form of the subject term. | +| [ICPSR Subject Term URI](#icpsr-subject-terms_uri) | Yes | No | Text | The URI for the subject term. | + + +##### ICPSR Subject Term + +**Description:** A human-readable form of the subject term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"employment" +``` + +```text +"marriage" +``` + +```text +"recidivism" +``` + + +##### ICPSR Subject Term Code + +**Description:** A machine-readable/-actionable form of the subject term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"25220" +``` + +```text +"26180" +``` + +```text +"26961" +``` + + +##### ICPSR Subject Term URI + +**Description:** The URI for the subject term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/25220" +``` + +```text +"https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/26180" +``` + +#### Complete ICPSR Subject Terms Examples (with Subfields): + +```yaml +- "ICPSR Subject Term": "lobbying" + "ICPSR Subject Term Code": "26131" + "ICPSR Subject Term URI": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/26131" + +- "ICPSR Subject Term": "age" + "ICPSR Subject Term Code": "24123" + "ICPSR Subject Term URI": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/24123" +``` + +```yaml +- "ICPSR Subject Term": "happiness" + "ICPSR Subject Term Code": "25624" + "ICPSR Subject Term URI": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/25624" +``` + + +--- + + +### Journal of Economic Literature (JEL) Classification Codes + +**Description:** Classification codes used to categorize economic research. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the American Economic Association's JEL Classifications Codes. Source: [https://www.aeaweb.org/jel/guide/jel.php](https://www.aeaweb.org/jel/guide/jel.php) + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#journal-of-economic-literature-(jel)-classification-codes_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#journal-of-economic-literature-(jel)-classification-codes_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#journal-of-economic-literature-(jel)-classification-codes_uri) | Yes | No | Text | The URI for the JEL classification code. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Relation of Economics to Other Disciplines" +``` + +```text +"History of Economic Thought, Methodology, and Heterodox Approaches" +``` + +```text +"Economic History: Financial Markets and Institutions: U.S.; Canada: 1913-" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"A12" +``` + +```text +"B00" +``` + +```text +"N22" +``` + + +##### URI + +**Description:** The URI for the JEL classification code. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/jelClassifications/terms/A12" +``` + +```text +"/api/v1/vocab-terms/jelClassifications/terms/B00" +``` + +```text +"/api/v1/vocab-terms/jelClassifications/terms/N22" +``` + +#### Complete Journal of Economic Literature (JEL) Classification Codes Examples (with Subfields): + +```yaml +- "Label": "Relation of Economics to Other Disciplines" + "Code": "A12" + "URI": "/api/v1/vocab-terms/jelClassifications/terms/A12" + +- "Label": "History of Economic Thought, Methodology, and Heterodox Approaches" + "Code": "B00" + "URI": "/api/v1/vocab-terms/jelClassifications/terms/B00" +``` + +```yaml +- "Label": "Economic History: Financial Markets and Institutions: U.S.; Canada: 1913-" + "Code": "N22" + "URI": "/api/v1/vocab-terms/jelClassifications/terms/N22" +``` + + +--- + + +### Medical Subject Headings (MeSH) Terms + +**Description:** Biomedical and health-related terms from the National Library of Medicine that describe the data collection's topics. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the National Library of Medicine's Medical Subject Headings (MeSH). Source: [https://www.ncbi.nlm.nih.gov/mesh/](https://www.ncbi.nlm.nih.gov/mesh/) + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#medical-subject-headings-(mesh)-terms_label) | Yes | No | Text | A human-readable form of the subject term. | +| [Code](#medical-subject-headings-(mesh)-terms_code) | Yes | No | Text | A machine-readable/-actionable form of the subject term. | +| [URI](#medical-subject-headings-(mesh)-terms_uri) | Yes | No | Text | The URI for the subject term as maintained in MeSH. | + + +##### Label + +**Description:** A human-readable form of the subject term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Anxiety" +``` + +```text +"Diabetes Mellitus" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the subject term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"D001007" +``` + +```text +"T011730" +``` + + +##### URI + +**Description:** The URI for the subject term as maintained in MeSH. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"http://id.nlm.nih.gov/mesh/D001007" +``` + +```text +"http://id.nlm.nih.gov/mesh/T011730" +``` + +#### Complete Medical Subject Headings (MeSH) Terms Examples (with Subfields): + +```yaml +- "Label": "Anxiety" + "Code": "D001007" + "URI": "http://id.nlm.nih.gov/mesh/D001007" + +- "Label": "Diabetes Mellitus" + "Code": "T011730" + "URI": "http://id.nlm.nih.gov/mesh/T011730" +``` + + +--- + + +### Time Periods + +**Description:** The time period(s) to which the data refer, regardless of when the data were collected. + +**Required:** Yes + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Start Date](#time-periods_start_date) | Yes | No | Text | The start date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions. | +| [End Date](#time-periods_end_date) | Yes | No | Text | The end date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions. | +| [Time Frame](#time-periods_time_frame) | No | No | Text | An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | + + +##### Start Date + +**Description:** The start date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"2000" +``` + +```text +"2019-10" +``` + +```text +"2021-03-01" +``` + + +##### End Date + +**Description:** The end date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"2000" +``` + +```text +"2019-10" +``` + +```text +"2021-03-01" +``` + + +##### Time Frame + +**Description:** An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The textual description ('time frame') is used to add context to the Time Period when multiple time periods exist (e.g., to describe different waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. + +The textual description should not simply restate the time period in words. For example, if the start and end dates for Time Period are 2020-01, the associated Time Frame should not be 'January 2020'. + +**Examples:** + +```text +"Fall 2001" +``` + +```text +"Winter Semester 2019" +``` + +#### Complete Time Periods Examples (with Subfields): + +```yaml +- "Start Date": "2018" + "End Date": "2018" + "Time Frame": "Summer and Fall 2018" + +- "Start Date": "2020-10" + "End Date": "2020-10" +``` + +```yaml +- "Start Date": "2003-01-01" + "End Date": "2003-12-31" +``` + + +--- + + +### Nationally Representative Sample + +**Description:** Indicates whether the data collection uses a sampling design intended to represent the demographics, behaviors, and/or characteristics of the entire nation. This typically involves probability-based methods that allow generalization. It does not include convenience samples that appear similar to the nation by chance. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Yes" +``` + +```text +"No" +``` + + +--- + + +### Geographic Coverage Areas + +**Description:** The geographic locations where the data refer or are related. + +**Required:** Yes + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** When choosing Geographic Coverage Areas: + +* Select the country, state, city, county, region, or continent covered by the study. +* Spell out place names completely instead of using acronyms. For example, enter "United States" instead of "USA." +* Type at least four characters to see matches. +* Choose only the narrowest level of geographic coverage. For example, if you select "Los Angeles, California, United States," do not also add "California, United States" and "United States." +* For studies with participants from around the world or that are applicable everywhere, select "Earth." + +Geographic locations are drawn from the GeoNames geographical database. Source: [https://www.geonames.org/](https://www.geonames.org/). Allowable feature codes include: + +* From Feature Class A (country, state, region,... – e.g., Administrative Divisions): + * ADM1 (first-order administrative division – e.g., US states, Canadian provinces, etc.) + * ADM2 (second-order administrative division – e.g. US counties) + * PCLI (independent political entity – e.g., countries) + * PCLD (dependent political entity – e.g., Puerto Rico and Guam) + * PCLF (freely associated state – e.g., Palau, Micronesia, and Marshall Islands) + * PCLH (historical political entity – e.g., former entities like Yugoslavia and USSR) + * PCLS (semi-independent political entity – e.g., Palestine, Macao, and Hong Kong) + * PCL (political entity – e.g., Guernsey, Jersey, and Isle of Man) + * TERR (territory – e.g., American Samoa, Svalbard and Jan Mayen, etc.) + * ZN (zone – e.g., European Union, Commonwealth of Nations, and NATO) +* From Feature Class P (city, village,... – e.g., Populated Places) + * PPLG (seat of government of a political entity) + * PPLC (capital of a political entity) + * PPLA (seat of a first-order administrative division) + * PPLA2 (seat of a second-order administrative division) + * PPL (populated place) +* From Feature Class L (parks,area, ..) + * RGN (region) + * CONT (continent) + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [City](#geographic-coverage-areas_city) | No | No | Text | A town, city, or similar populated place covered in the data collection | +| [County](#geographic-coverage-areas_county) | No | No | Text | A United States county or similar administrative area covered in the data collection | +| [State](#geographic-coverage-areas_state) | No | No | Text | A state, province, canton or similar political entity covered in the data collection | +| [Country](#geographic-coverage-areas_country) | No | No | Text | A country covered in the data collection | +| [Region](#geographic-coverage-areas_region) | No | No | Text | An area distinguished by one or more observable physical or cultural characteristics that is covered in the data collection. | +| [Continent](#geographic-coverage-areas_continent) | No | No | Text | A continent covered in the data collection | +| [Other Geographic Area](#geographic-coverage-areas_other_area) | No | No | Text | An area covered in the data collection that cannot be represented using the defined categories above or matched to an appropriate GeoNames record. | +| [URI](#geographic-coverage-areas_uri) | No | No | Text | A local unique identifier for the geographic coverage area. | +| [External URI](#geographic-coverage-areas_externalURI) | No | No | Text | The GeoNames unique identifier for the geographic coverage area. | + + +##### City + +**Description:** A town, city, or similar populated place covered in the data collection + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Ann Arbor" +``` + +```text +"Hanover" +``` + +```text +"Chongqing" +``` + + +##### County + +**Description:** A United States county or similar administrative area covered in the data collection + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Monroe County" +``` + +```text +"Washtenaw County" +``` + +```text +"Cuyahoga County" +``` + + +##### State + +**Description:** A state, province, canton or similar political entity covered in the data collection + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Michigan" +``` + +```text +"Manitoba" +``` + +```text +"Yunnan" +``` + + +##### Country + +**Description:** A country covered in the data collection + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"United States" +``` + +```text +"China" +``` + +```text +"Ghana" +``` + + +##### Region + +**Description:** An area distinguished by one or more observable physical or cultural characteristics that is covered in the data collection. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Sub-Saharan Africa" +``` + +```text +"Eastern Europe" +``` + +```text +"Siberia" +``` + + +##### Continent + +**Description:** A continent covered in the data collection + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Africa" +``` + +```text +"Asia" +``` + +```text +"South America" +``` + + +##### Other Geographic Area + +**Description:** An area covered in the data collection that cannot be represented using the defined categories above or matched to an appropriate GeoNames record. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** Use this for user-provided terms, loosely defined geographic concepts, GeoNames feature types not covered by city/county/state/country/region/continent, or historical geographic entities (e.g., Prussia) not represented in GeoNames. + +**Examples:** + +```text +"Global" +``` + +```text +"Eurasia" +``` + +```text +"13 U.S. states in 3 regions" +``` + + +##### URI + +**Description:** A local unique identifier for the geographic coverage area. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/geoNames/terms/6252001" +``` + +```text +"/api/v1/vocab-terms/geoNames/terms/6269554" +``` + + +##### External URI + +**Description:** The GeoNames unique identifier for the geographic coverage area. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://sws.geonames.org/4990729/" +``` + +```text +"https://sws.geonames.org/6269554" +``` + +#### Complete Geographic Coverage Areas Examples (with Subfields): + +```yaml +- "City": "Cleveland" + "State": "Ohio" + "Country": "United States" + "Continent": "North America" + "External URI": "https://sws.geonames.org/5150529" + "URI": "/api/v1/vocab-terms/geoNames/terms/5150529" + +- "County": "Washtenaw County" + "State": "Michigan" + "Country": "United States" + "Continent": "North America" + "External URI": "https://sws.geonames.org/5014120" + "URI": "/api/v1/vocab-terms/geoNames/terms/5014120" + +- "State": "Pennsylvania" + "Country": "United States" + "Continent": "North America" + "External URI": "https://sws.geonames.org/5206379" + "URI": "/api/v1/vocab-terms/geoNames/terms/5206379" +``` + +```yaml +- "Country": "Germany" + "Continent": "Europe" + "External URI": "https://sws.geonames.org/2921044" + "URI": "/api/v1/vocab-terms/geoNames/terms/2921044" + +- "Continent": "Africa" + "External URI": "https://sws.geonames.org/6255146" + "URI": "/api/v1/vocab-terms/geoNames/terms/6255146" +``` + +```yaml +- "Other Geographic Area": "Global" + "External URI": "https://sws.geonames.org/6295630" + "URI": "/api/v1/vocab-terms/geoNames/terms/6295630" +``` + +```yaml +- "Other Geographic Area": "13 U.S. states in 3 regions" +``` + + +--- + + +### Smallest Geographic Unit + +**Description:** The smallest geographic unit (e.g., state or census tract) used in the dataset. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** Smallest Geographic Unit is intended to represent specific, known geography – e.g., county, census district, Zip code, electoral district, etc. – that is represented by a variable. + +If the data do not include a geographic variable by which the data can be analyzed, this element is not indicated. If all the cases are from a single state, but the cases are not subdivided geographically within that state, then 'state' is not indicated. + +If there is a variable indicating which testing site a survey was taken at, but the locations of the testing sites were masked by the PI, this element is likely not indicated. + + +This field employs a local ICPSR controlled vocabulary; see below for terms and definitions: + + +| Term | Definition | +|------|------------| +| Geocoded Location | A precise geographic point derived from an address, typically represented as coordinates or address strings. | +| Parcel | A discrete use of land ownership, often defined in property records or tax assessments. | +| Grid Cell | A unit of spatial data that divides an area into rectangular, square intervals (e.g., 1km x 1km grid), typically used in mapping or environmental studies. | +| Postal Code/Zip Code | A geographic area defined by postal delivery routes or regions, used for organizing mail delivery. | +| Neighborhood/Community Area | An informally defined area within a city, usually based on local recognition rather than official administrative boundaries. | +| City/Municipality | A local government jurisdiction that covers urban areas, which can range from large cities to small towns and villages. | +| County/District/Parish | A geographic area that is part of a state or province (e.g., parishes in Louisiana, boroughs in Alaska). | +| State/Province | A major administrative division within a country. In the U.S., this includes the 50 states and the District of Columbia. Other countries, like Canada and Australia, have provinces or states (e.g., Ontario in Canada, New South Wales in Australia). | +| Territory | A region under the jurisdiction of a national government, but not a fully self-governing state or province (e.g., Puerto Rico, Northwest Territories, Falkland Islands). | +| Country | A sovereign nation or territory that is recognized as an independent political entity, such as the United States, Canada, or France. | +| Census Block | The smallest geographic unit used in national censuses, often corresponding to a city block or small neighborhood. | +| Census Block Group | A collection of adjacent census blocks—typically all blocks within part of a census tract. | +| Census Tract | A small geographic unit used in national censuses, typically representing 2,500 to 8,000 people. Census tracts are designed to provide detailed statistical data for neighborhoods or communities. | +| Census Division | A larger geographic area used for statistical reporting, grouping states or provinces within a country. Census divisions are smaller than regions but larger than individual states or provinces. | +| Census Region | A broader grouping of census divisions used to organize and report data at a national level (e.g., Northeast, Midwest, South, West). | +| Public Use Microdata Area (PUMA) | A geographic area with a population of 100,000 or more, used for the release of detailed public-use microdata from the U.S. Census. | +| Core-Based Statistical Area (CBSA) | A term that includes both Metropolitan and Micropolitan Statistical Areas. These areas are based on urban centers and their surrounding communities as defined by the U.S. Office of Management and Budget (OMB). | +| Metropolitan Statistical Area (MSA) | A Core-Based Statistical Area (CBSA) that includes an urban core with a population of 50,000 or more. | +| Micropolitan Statistical Area | A Core-Based Statistical Area (CBSA) that includes an urban core population of at least 10,000 but less than 50,000. | +| ZIP Code Tabulation Area (ZCTA) | A geographic area created by the U.S. Census Bureau to approximate the boundaries of ZIP Codes for demographic analysis. | +| Voting District/Precinct | A geographic area used for organizing elections, often serving as the smallest electoral units where voters cast their ballots. | +| Congressional District | A geographic area used for electing representatives to federal or state legislative offices in the United States. | +| Federal Court District | A geographic area where a U.S. District Court has jurisdiction to hear and decide federal cases. | +| School District | The administrative boundary for local education systems, typically overseeing public schools from elementary through secondary levels. | +| Indigenous/Tribal Lands | An area legally recognized as an Indigenous or tribal nation, often with unique legal, cultural, or sovereignty status. | + + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#smallest-geographic-unit_label) | No | No | Text | A human-readable form of the term. | +| [Code](#smallest-geographic-unit_code) | No | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#smallest-geographic-unit_uri) | No | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Basic Geographic Units" +``` + +```text +"Postal Code/Zip Code" +``` + +```text +"State/Province" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"BasicUnits" +``` + +```text +"PostalCodeZipCode" +``` + +```text +"StateProvince" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/smallestGeographicUnits/terms/BasicUnits" +``` + +```text +"/api/v1/vocab-terms/smallestGeographicUnits/terms/PostalCodeZipCode" +``` + +```text +"/api/v1/vocab-terms/smallestGeographicUnits/terms/StateProvince" +``` + +#### Complete Smallest Geographic Unit Examples (with Subfields): + +```yaml +"Label": "Basic Geographic Units" +"Code": "BasicUnits" +"URI": "/api/v1/vocab-terms/smallestGeographicUnits/terms/BasicUnits" +``` + +```yaml +"Label": "Postal Code/Zip Code" +"Code": "PostalCodeZipCode" +"URI": "/api/v1/vocab-terms/smallestGeographicUnits/terms/PostalCodeZipCode" +``` + +```yaml +"Label": "State/Province" +"Code": "StateProvince" +"URI": "/api/v1/vocab-terms/smallestGeographicUnits/terms/StateProvince" +``` + + +--- + + +### Study Design + +**Description:** The procedures used to contact participants and gather data. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The Study Design provides more detailed information than the Summary, including how surveys were prepared and administered, how interviews were conducted, or how the data were obtained and compiled, as well as information about deadlines and follow-ups to respondents. + +**Examples:** + +```text +"Data on organizational culture in each of the 12 courts (Part 1) were obtained by administering the Court Culture Assessment Instrument (CCAI) to all judges with a felony criminal court docket and to all senior court administrators. A total of 224 respondents completed the questionnaire. The CCAI was used to assess five key dimensions of current court culture orientation: (1) dominant case management style, (2) judicial and court staff relations, (3) change management, (4) courthouse leadership, and (5) internal organization. The determination of what culture judges and court administrators desired to establish in the near future was also obtained through the application of the same instrument (CACI) as practitioners were asked to indicate the type of culture in each work area (or content dimension) they would like to see in their court in the next five years." +``` + + +--- + + +### Universe + +**Description:** The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** Age, nationality, and residence commonly help to delineate a given universe, but any of a number of factors may be involved, such as sex, race, income, veteran status, criminal convictions, etc. The Universe may consist of elements other than persons, such as housing units, court cases, deaths, countries, etc. It should be possible to tell from the description of the universe whether a given individual or element (hypothetical or real) is a member of the population under study. Typically, the Universe statement is about one sentence or shorter, and reflects the entire possible population a data collection sought to study. + +**Examples:** + +```text +"All households in the United States with phones." +``` + +```text +"Part 1: Thirty cities in Massachusetts during 1980-1986. Parts 2-4: All residents in Massachusetts during 1986." +``` + +```text +"Individuals self-identified as transgender, trans, genderqueer, non-binary, or other identities on the transgender identity spectrum aged 18 and older residing in the fifty U.S. states, the District of Columbia, American Samoa, Guam, Puerto Rico, and U.S. military bases overseas." +``` + +```text +"Jihadists from the United States and Canada, along with Incels from Germany, Canada, the United States, and United Kingdom." +``` + +```text +"All publicly funded medical examiner and coroner offices." +``` + +```text +"Uncertified ballots for the 2000 United States presidential election in Florida." +``` + + +--- + + +### Time Methods + +**Description:** The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV TimeMethod [https://rdf-vocabulary.ddialliance.org/ddi-cv/TimeMethod/1.2.3/TimeMethod.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/TimeMethod/1.2.3/TimeMethod.html). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#time-methods_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#time-methods_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#time-methods_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Cross-section" +``` + +```text +"Longitudinal: Panel" +``` + +```text +"Time series" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"CrossSection" +``` + +```text +"Longitudinal.Panel" +``` + +```text +"TimeSeries" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/timeMethods/terms/CrossSection" +``` + +```text +"/api/v1/vocab-terms/timeMethods/terms/Longitudinal.Panel" +``` + +```text +"/api/v1/vocab-terms/timeMethods/terms/TimeSeries" +``` + +#### Complete Time Methods Examples (with Subfields): + +```yaml +- "Label": "Cross-section" + "Code": "CrossSection" + "URI": "/api/v1/vocab-terms/timeMethods/terms/CrossSection" + +- "Label": "Longitudinal: Panel" + "Code": "Longitudinal.Panel" + "URI": "/api/v1/vocab-terms/timeMethods/terms/Longitudinal.Panel" +``` + +```yaml +- "Label": "Time series" + "Code": "TimeSeries" + "URI": "/api/v1/vocab-terms/timeMethods/terms/TimeSeries" +``` + + +--- + + +### Units of Analysis + +**Description:** The object(s) of analysis for the data collection, such as an organization, individual, or household. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV AnalysisUnit [https://rdf-vocabulary.ddialliance.org/ddi-cv/AnalysisUnit/2.1.3/AnalysisUnit.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/AnalysisUnit/2.1.3/AnalysisUnit.html). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#units-of-analysis_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#units-of-analysis_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#units-of-analysis_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Organization/Institution" +``` + +```text +"Individual" +``` + +```text +"Household" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"OrganizationOrInstitution" +``` + +```text +"Individual" +``` + +```text +"Household" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/analysisUnits/OrganizationOrInstitution" +``` + +```text +"/api/v1/vocab-terms/analysisUnits/Individual" +``` + +```text +"/api/v1/vocab-terms/analysisUnits/Household" +``` + +#### Complete Units of Analysis Examples (with Subfields): + +```yaml +- "Label": "Organization/Institution" + "Code": "OrganizationOrInstitution" + "URI": "/api/v1/vocab-terms/analysisUnits/OrganizationOrInstitution" + +- "Label": "Individual" + "Code": "Individual" + "URI": "/api/v1/vocab-terms/analysisUnits/Individual" +``` + +```yaml +- "Label": "Household" + "Code": "Household" + "URI": "/api/v1/vocab-terms/analysisUnits/Household" +``` + + +--- + + +### Sampling Procedures + +**Description:** The type(s) of sample and sample design used to select survey respondents to represent the population. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Usage Notes:** The sample is a selection out of the universe of all possible relevant cases (e.g., adults in the United States, housing units in three counties of Michigan, etc.) that could have been included in the data collection. Note that some studies, such as censuses, do not utilize samples but include all members of the universe. + +This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV SamplingProcedure [https://rdf-vocabulary.ddialliance.org/ddi-cv/SamplingProcedure/1.1.4/SamplingProcedure.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/SamplingProcedure/1.1.4/SamplingProcedure.html) + +**Examples:** + +```yaml +- "Label": "Probability: Systematic random" + "Code": "Probability.SystematicRandom" + "Uri": "/api/v1/vocab-terms/samplingProcedures/terms/Probability.SystematicRandom" + +- "Label": "Theoretical Sampling" + "Code": "TheoreticalSampling" + "Uri": "/api/v1/vocab-terms/samplingProcedures/terms/TheoreticalSampling" +``` + +```yaml +- "Label": "Total universe/Complete enumeration" + "Code": "TotalUniverseCompleteEnumeration" + "Uri": "/api/v1/vocab-terms/samplingProcedures/terms/TotalUniverseCompleteEnumeration" +``` + + +--- + + +### Sampling Note + +**Description:** Supplemental information about the sampling process that does not fit neatly into the Sampling Procedure field. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** A detailed discussion of such things as sampling error or other limitations of the sampling methodology is not required here. + +**Examples:** + +```text +"National sample of telephone numbers from cell (RDD) sampling frame." +``` + +```text +"The probability sample selected to represent the universe consists of approximately 71,000 households." +``` + + +--- + + +### Weights + +**Description:** The weight variables and the criteria for using them in data analysis, or other information about how the data are weighted if no weight variables are present. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** Weight includes any information about weighting variables in the data, as well as any other weight information provided by the Principal Investigator. If a weighting formula or coefficient was developed, provide this formula, define its elements, and indicate how the formula is applied to the data. It is acceptable to summarize additional documentation and refer users to those resources for more information. + +**Examples:** + +```text +"Both the TransPop and Cisgender datasets have the same variable named WEIGHT as the weighting variable. The combination datasets have a set of three weight variables (WEIGHT_TRANSPOP, WEIGHT_CISGENDER, WEIGHT_CISGENDER_TRANSPOP)" +``` + +```text +"A weight variable with two implied decimal places has been included and must be used in any analysis." +``` + + +--- + + +### Response Rates + +**Description:** The percentage of respondents in the sample who participated in the data collection. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** This field is only applicable if the data were collected with a survey instrument and the response rates are provided. + +**Examples:** + +```text +"The overall response rate for this survey was 20.22%; 72.6% for existing panelists and 10.4% for new panelists, using AAPOR Response Rate 1." +``` + +```text +"Of the 1,843 Midlife in the United States (MIDUS) respondents that researchers attempted to contact, 1,483 agreed to participate (8 percent refused participation and 11 percent either moved or were difficult to contact), yielding a response rate of approximately 81 percent." +``` + + +--- + + +### Data Source Types + +**Description:** The source(s) of the data as collected by the Principal Investigators. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** People, things, and other data can all be Data Source Types. This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV DataSourceType [https://rdf-vocabulary.ddialliance.org/ddi-cv/DataSourceType/1.0.2/DataSourceType.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/DataSourceType/1.0.2/DataSourceType.html). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#data-source-types_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#data-source-types_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#data-source-types_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Registers/Records/Accounts: Medical/Clinical" +``` + +```text +"Events/Interactions" +``` + +```text +"Research data: Published" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"RegistersRecordsAccounts.MedicalClinical" +``` + +```text +"EventsInteractions" +``` + +```text +"ResearchData.Published" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/dataSourceTypes/terms/RegistersRecordsAccounts.MedicalClinical" +``` + +```text +"/api/v1/vocab-terms/dataSourceTypes/terms/EventsInteractions" +``` + +```text +"/api/v1/vocab-terms/dataSourceTypes/terms/ResearchData.Published" +``` + +#### Complete Data Source Types Examples (with Subfields): + +```yaml +- "Label": "Registers/Records/Accounts: Medical/Clinical" + "Code": "RegistersRecordsAccounts.MedicalClinical" + "URI": "/api/v1/vocab-terms/dataSourceTypes/terms/RegistersRecordsAccounts.MedicalClinical" + +- "Label": "Events/Interactions" + "Code": "EventsInteractions" + "URI": "/api/v1/vocab-terms/dataSourceTypes/terms/EventsInteractions" +``` + +```yaml +- "Label": "Research data: Published" + "Code": "ResearchData.Published" + "URI": "/api/v1/vocab-terms/dataSourceTypes/terms/ResearchData.Published" +``` + + +--- + + +### External Data Sources + +**Description:** The source of the data, when that source is external to the data collection and can be independently cited. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Usage Notes:** External data sources can include websites, datasets, books, journal articles, and other sources. Each source includes at minimum the title, author, publication year, journal (if applicable), and DOI or URL for online sources. Any citation format is accepted. + +**Examples:** + +```text +"'Voting Scores.' Congressional Quarterly Almanac 33 (1977), 487-498" +``` + +```text +"Multi-Resolution Land Characteristics Consortium. "National Land Cover Database (CONUS), All Years," 2016. https://www.mrlc.gov/data/nlcd-land-cover-conus-all-years" +``` + +```text +"Data file 1: United States Census Bureau (2010). TIGER/Line shapefiles, 2010 census tracts (2010 version) [Data set]. https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_01_tract10.zip" +``` + + +--- + + +### Collection Modes + +**Description:** The method(s) or procedure(s) used to collect the data, such as an interview or experiment. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV ModeOfCollection [https://rdf-vocabulary.ddialliance.org/ddi-cv/ModeOfCollection/4.0.3/ModeOfCollection.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/ModeOfCollection/4.0.3/ModeOfCollection.html). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#collection-modes_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#collection-modes_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#collection-modes_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Face-to-face interview: Computer-assisted (CAPI/CAMI)" +``` + +```text +"Measurements and tests" +``` + +```text +"Computer-based observation" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Interview.FaceToFace.CAPIorCAMI" +``` + +```text +"MeasurementsAndTests" +``` + +```text +"Observation.ComputerBased" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/collectionModes/terms/Interview.FaceToFace.CAPIorCAMI" +``` + +#### Complete Collection Modes Examples (with Subfields): + +```yaml +- "Label": "Face-to-face interview: Computer-assisted (CAPI/CAMI)" + "Code": "Interview.FaceToFace.CAPIorCAMI" + "URI": "/api/v1/vocab-terms/collectionModes/terms/Interview.FaceToFace.CAPIorCAMI" +``` + +```yaml +- "Label": "Measurements and tests" + "Code": "MeasurementsAndTests" + "URI": "/api/v1/vocab-terms/collectionModes/terms/MeasurementsAndTests" + +- "Label": "Computer-based observation" + "Code": "Observation.ComputerBased" + "URI": "/api/v1/vocab-terms/collectionModes/terms/Observation.ComputerBased" +``` + + +--- + + +### Collection Dates + +**Description:** The date(s) data collection took place. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Start Date](#collection-dates_start_date) | Yes | No | Text | The start date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces. | +| [End Date](#collection-dates_end_date) | Yes | No | Text | The end date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces. | +| [Time Frame](#collection-dates_time_frame) | No | No | Text | An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. | + + +##### Start Date + +**Description:** The start date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"2000" +``` + +```text +"2019-10" +``` + +```text +"2021-03-01" +``` + + +##### End Date + +**Description:** The end date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"2000" +``` + +```text +"2019-10" +``` + +```text +"2021-03-01" +``` + + +##### Time Frame + +**Description:** An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The textual description ('time frame') is used to add context to the Collection Date when multiple time periods exist (e.g., to describe different study waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. + +The textual description should not simply restate the time period in words. For example, if the Collection Date is 2020-01, the Time Frame should not be 'January 2020'. + +**Examples:** + +```text +"Fall 2001" +``` + +```text +"Student data" +``` + +#### Complete Collection Dates Examples (with Subfields): + +```yaml +- "Start Date": "2018" + "End Date": "2018" + "Time Frame": "Wave 1" + +- "Start Date": "2020-10" + "End Date": "2020-10" + "Time Frame": "Wave 2" +``` + +```yaml +- "Start Date": "2003-01-01" + "End Date": "2003-12-31" +``` + + +--- + + +### Variable Description + +**Description:** Significant variables (particularly demographic variables) in the data files. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The Variable Description provides more detailed information than the Summary, including a review of variables that are important for users to know about. The codebook, setup files, and variable groups are appropriate sources of information for Variable Description. + +**Examples:** + +```text +"The data includes variables about participants' and their parents' moods, interviewer observations, families' activities, families' health history, participants' school records, and parents' substance use. Demographic variables include race, religion, annual household income, and the participants' parents' employment statuses." +``` + +```text +"The LGBTQ Hate Crimes Interviews dataset contains more in-depth information, including victim demographic information, substance abuse history, information on whether the victim is open about their LGBTQ identification, the victim's job status, and information about how the victim reacted to the crime, such as whether or not they reported the crime to the police and their level of cooperation with the police and prosecution." +``` + + +--- + + +### Scales + +**Description:** Any commonly known scales, measures, or inventories used in the data collection. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** Include common scales that can be readily identified from the data, documentation, or other related materials. Examples of common scales include the Minnesota Multiphasic Personality Inventory (MMPI) and the Consumer Price Index (CPI). ICPSR curators are not expected to infer or research scales that are not explicitly indicated. The scales can be cited either as a list or described in full sentences and include DOIs or URLs whenever possible. If the questionnaire used has a finite list of responses (e.g., 'Always, Sometimes, Rarely, Never' or 'Strongly Agree, Agree, Disagree, Strongly Disagree'), it is acceptable for this element to note 'A Likert-type scale was used,' or 'Several Likert-type scales were used.' However, it is not required to note Likert-type scales in situations where only such scales were used, given their ubiquity. + +**Examples:** + +```text +"The baseline data collection included one scale - the CES-D index for maternal depression [Cole, J. C., Rabin, A. S., Smith, T. L., and Kaufman, A. S. (2004). Development and validation of a Rasch-derived CES-D short form. Psychological assessment, 16(4), 360. https://doi.org/10.1037/1040-3590.16.4.360]. All scales used for outcomes at ages 1 through 3 are listed in Appendix Tables 1 and 2 in the User Guide. Please refer to the User Guide and P.I. Codebook, available under the 'Data and Documentation' tab, for details." +``` + +```text +"Squires, J., Bricker, D. D., and Twombly, E. (2009). Ages and stages questionnaires. Baltimore, MD: Paul H. Brookes." +"Briggs-Gowan, M. J., Carter, A. S., Irwin, J. R., Wachtel, K., and Cicchetti, D. V. (2004). The Brief Infant-Toddler Social and Emotional Assessment: screening for social-emotional problems and delays in competence. Journal of pediatric psychology, 29(2), 143-155. https://doi.org/10.1093/jpepsy/jsh017" +"Yu, L., Buysse, D. J., Germain, A., Moul, D. E., Stover, A., Dodds, N. E., ... and Pilkonis, P. A. (2012). Development of short forms from the PROMIS sleep disturbance and sleep-related impairment item banks. Behavioral sleep medicine, 10(1), 6-24. https://doi.org/10.1080/15402002.2012.636266" +``` + + +--- + + +### Data Management Plan + +**Description:** A link to the data management plan (preferably a persistent identifier such as a DOI). + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://doi.org/10.48321/D1EA6EF78D" +``` + +```text +"https://rdm.mcmaster.ca/dmps/promoting-healthy-families-data-management-plan" +``` + + +--- + + +### Preregistration + +**Description:** A link to a research plan for the data collection (preferably a persistent identifier such as a DOI). + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://doi.org/10.17605/OSF.IO/67DUT" +``` + +```text +"https://doi.org/10.1257/rct.15789-1.0" +``` + + +--- + + +### Software Applications + +**Description:** Software used by the principal investigator(s) to collect or analyze data, required to understand how the data were obtained or to reproduce results. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Software Name](#software-applications_name) | Yes | No | Text | The name of the software application. | +| [Software Version](#software-applications_software_version) | No | No | Text | The version of the application. | +| [Software Description](#software-applications_description) | No | No | Text | Short description or overview of the application and its intended purpose | +| [Programming Languages](#software-applications_programming_languages) | No | Yes | Text | The programming language(s) used in the development of the application | +| [Operating Systems](#software-applications_operating_systems) | No | Yes | Text | Computer operating systems supported by the application | +| [Memory Requirements](#software-applications_memory_requirements) | No | No | Text | Minimum memory (e.g., RAM) requirements to operate the application | +| [Processor Requirements](#software-applications_processor_requirements) | No | No | Text | Processor architecture required to run the application | +| [Software Requirements](#software-applications_software_requirements) | No | No | Text | Required components for the application, like runtime environments and shared libraries not included in the package but needed to run it. | +| [Storage Requirements](#software-applications_storage_requirements) | No | No | Text | Amount of storage space required by the application | +| [Device Requirements](#software-applications_device_requirements) | No | No | Text | Device required to run the application. Used in cases where a specific make/model is required to run the application | +| [License](#software-applications_license) | No | No | Text | The license associated with the application, preferably expressed as a URL. | +| [Download URL](#software-applications_download_url) | No | No | Text | A direct link to a downloadable software artifact (e.g., executable, package, archive, or single script file) that retrieves the application itself, without additional navigation or instructions. | +| [Installation URL](#software-applications_install_url) | No | No | Text | A link to a repository or project landing page where users can obtain resources and instructions to install the application (as opposed to directly downloading a single file). | + + +##### Software Name + +**Description:** The name of the software application. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"JHOVE" +``` + +```text +"ffmpeg" +``` + +```text +"json-schema-for-humans" +``` + + +##### Software Version + +**Description:** The version of the application. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"1" +``` + +```text +"2.0.4" +``` + +```text +"Auto-Build 2023-01-15 12:36" +``` + + +##### Software Description + +**Description:** Short description or overview of the application and its intended purpose + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"JHOVE, the JSTOR/Harvard Object Validation Environment, is an extensible software framework for performing format identification, validation, and characterization of digital objects." +``` + +```text +"ffmpeg is a very fast video and audio converter that can also grab from a live audio/video source. It can also convert between arbitrary sample rates and resize video on the fly with a high quality polyphase filter." +``` + + +##### Programming Languages + +**Description:** The programming language(s) used in the development of the application + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Examples:** + +```text +"python" +``` + +```text +"shell" +"r" +``` + +```text +"other" +``` + + +##### Operating Systems + +**Description:** Computer operating systems supported by the application + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Examples:** + +```text +"windows" +``` + +```text +"windows" +"mac" +"linux" +``` + +```text +"other" +``` + + +##### Memory Requirements + +**Description:** Minimum memory (e.g., RAM) requirements to operate the application + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"4 GB" +``` + +```text +"1GB of RAM (2GB for a 64-bit version)" +``` + +```text +"4 GB of GPU memory for HD and some 4K media; 6 GB or more for 4K and higher" +``` + + +##### Processor Requirements + +**Description:** Processor architecture required to run the application + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Intel i5/ i7/ Ryzen 7" +``` + +```text +"Minimum 1 GHz; Recommended 2GHz or more" +``` + +```text +"2.5–2.9 GHz or faster processor" +``` + + +##### Software Requirements + +**Description:** Required components for the application, like runtime environments and shared libraries not included in the package but needed to run it. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Java runtime environment" +``` + +```text +"Requires additional Python libraries: numpy, v1.11.2; scipy, v0.18.1, and pandas, v0.19.0" +``` + +```text +"Compile with GNU auto tools" +``` + + +##### Storage Requirements + +**Description:** Amount of storage space required by the application + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"3.5 GB for new installations, 5 GB for upgrades (including temporary files required during installation)" +``` + +```text +"15 GB of free disk space" +``` + +```text +"8 GB of available hard-disk space for installation; additional free space required during installation" +``` + + +##### Device Requirements + +**Description:** Device required to run the application. Used in cases where a specific make/model is required to run the application + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + + +##### License + +**Description:** The license associated with the application, preferably expressed as a URL. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://www.apache.org/licenses/LICENSE-2.0" +``` + +```text +"https://opensource.org/licenses/LGPL-2.0" +``` + + +##### Download URL + +**Description:** A direct link to a downloadable software artifact (e.g., executable, package, archive, or single script file) that retrieves the application itself, without additional navigation or instructions. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://github.com/richardlehane/siegfried/archive/refs/heads/main.zip" +``` + +```text +"https://cdn.nationalarchives.gov.uk/documents/droid-binary-6.5.2-bin-win32-with-jre.zip" +``` + + +##### Installation URL + +**Description:** A link to a repository or project landing page where users can obtain resources and instructions to install the application (as opposed to directly downloading a single file). + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://github.com/richardlehane/siegfried" +``` + +```text +"https://www.nationalarchives.gov.uk/information-management/manage-information/preserving-digital-records/droid/" +``` + +#### Complete Software Applications Examples (with Subfields): + +```yaml +- "Software Name": "siegfried" + "Software Version": "1.11.1" + "Software Description": "Siegfried is a signature-based file format identification\ + \ tool, implementing the National Archives UK's PRONOM file format signatures;\ + \ freedesktop.org's MIME-info file format signatures; the Library of Congress's\ + \ FDD file format signatures (beta); and Wikidata (beta)." + "Programming Languages": + - "go" + - "javascript" + - "other" + "Operating Systems": + - "mac" + - "linux" + - "windows" + "License": "https://www.apache.org/licenses/LICENSE-2.0" + "Download URL": "https://github.com/richardlehane/siegfried/archive/refs/heads/main.zip" +``` + + +--- + + +### General Data Formats + +**Description:** The file format types present in the data collection. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV GeneralDataFormat [https://rdf-vocabulary.ddialliance.org/ddi-cv/GeneralDataFormat/2.0.3/GeneralDataFormat.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/GeneralDataFormat/2.0.3/GeneralDataFormat.html). + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#general-data-formats_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#general-data-formats_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#general-data-formats_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Text" +``` + +```text +"Still image" +``` + +```text +"Numeric" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Text" +``` + +```text +"StillImage" +``` + +```text +"Numeric" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +#### Complete General Data Formats Examples (with Subfields): + +```yaml +- "Label": "Text" + "Code": "Text" + "URI": "/api/v1/vocab-terms/generalDataFormats/terms/Text" + +- "Label": "Still image" + "Code": "StillImage" + "URI": "/api/v1/vocab-terms/generalDataFormats/terms/StillImage" +``` + +```yaml +- "Label": "Numeric" + "Code": "Numeric" + "URI": "/api/v1/vocab-terms/generalDataFormats/terms/Numeric" +``` + + +--- + + +### Notes + +**Description:** Important details about the data collection (like unique authoring, discrepancies, or processing information) that can't be recorded in other metadata elements. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Text + +**Usage Notes:** Notes should include any information that does not fit anywhere else in the metadata, such as: information about unique aspects of the way the data was processed, discrepancies between the metadata and documentation files, information about the research team, or series-specific notes. + +**Examples:** + +```text +"Information on the Index of Consumer Sentiment, the Index of Current Economic Conditions, and the Index of Consumer Expectations and how they were created can be found in the P.I. Codebook" +"Dataset 1 should be attributed to Jane Doe while datasets 2-6 should be attributed to John Doe" +``` + +```text +"Additional information on the Survey of Consumers can be found by visiting the Survey of Consumers Website" +``` + + +--- + + +### Manuscript Number + +**Description:** A unique identifier that associates the data collection with a manuscript submitted to a journal. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"ECIN-Mar-2025-0078.R2" +``` + +```text +"AER-2019-0000" +``` + + +--- + + +### ADA Accessibility + +**Description:** Indicates whether the data collection is ADA accessible, conforming to WCAG 2.1 AA standards, or qualifies for the ADA archival exception. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +**Usage Notes:** This field employs a local ICPSR controlled vocabulary; see below for terms and definitions: + + +| Term | Definition | +|------|------------| +| ADA Accessible | The item is ADA accessible, conforming to WCAG 2.1 AA standards. | +| ADA Archival | The item is not ADA accessible, but qualifies for the ADA archival exception. | + + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#ada-accessibility_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#ada-accessibility_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#ada-accessibility_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"ADA Accessible" +``` + +```text +"ADA Archival" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"ada.accessible" +``` + +```text +"ada.archival" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/adaAccessibility/terms/ada.accessible" +``` + +```text +"/api/v1/vocab-terms/adaAccessibility/terms/ada.archival" +``` + +#### Complete ADA Accessibility Examples (with Subfields): + +```yaml +"Label": "ADA Accessible" +"Code": "ada.accessible" +"URI": "/api/v1/vocab-terms/adaAccessibility/terms/ada.accessible" +``` + +```yaml +"Label": "ADA Archival" +"Code": "ada.archival" +"URI": "/api/v1/vocab-terms/adaAccessibility/terms/ada.archival" +``` + + +--- + + +### License + +**Description:** A license governing the data's use. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Label](#license_label) | Yes | No | Text | A human-readable form of the term. | +| [Code](#license_code) | Yes | No | Text | A machine-readable/-actionable form of the term. | +| [URI](#license_uri) | Yes | No | Text | The URI for the term. | + + +##### Label + +**Description:** A human-readable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Creative Commons Attribution 4.0 International" +``` + +```text +"Apache License 1.0" +``` + + +##### Code + +**Description:** A machine-readable/-actionable form of the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"CC-BY-NC-4.0" +``` + +```text +"Apache-1.0" +``` + + +##### URI + +**Description:** The URI for the term. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"/api/v1/vocab-terms/licenses/terms/CC-BY-4.0" +``` + +```text +"/api/v1/vocab-terms/licenses/terms/Apache-1.0" +``` + +#### Complete License Examples (with Subfields): + +```yaml +"Label": "Creative Commons Attribution 4.0 International" +"Code": "CC-BY-NC-4.0" +"URI": "/api/v1/vocab-terms/licenses/terms/CC-BY-4.0" +``` + +```yaml +"Label": "Apache License 1.0" +"Code": "Apache-1.0" +"URI": "/api/v1/vocab-terms/licenses/terms/Apache-1.0" +``` + + +--- + + +### Version History + +**Description:** A record of how the data collection has changed over time. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Version Number](#version-history_version_number) | No | No | Text | A version number for a study. | +| [Version Date](#version-history_version_date) | No | No | Text | The date on which a given version of a data collection was released. | +| [Version Note](#version-history_version_note) | No | No | Text | Provenance information about a given version of the data collection. | + + +##### Version Number + +**Description:** A version number for a study. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** Every ICPSR data collection is assigned version 1.0 when it is first published. When the data collection is updated, a new version number is assigned. For substantive changes to the data collection, including changes to data files, title, or principal investigators, a new major version is created, the version number increases by 1 (for example, from 1.0 to 2.0), and a new version-specific digital object identifier (DOI) is created. For all other changes, a new minor version is created, the version number increases by 0.1 (for example, from 2.0 to 2.1), and the DOI does not change. + +**Examples:** + +```text +"V1" +``` + +```text +"V2.1" +``` + +```text +"V3.2" +``` + + +##### Version Date + +**Description:** The date on which a given version of a data collection was released. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** ICPSR automatically generates this date for data collection additions and updates. + +**Examples:** + +```text +"2020-07-20" +``` + +```text +"2022-01-31" +``` + + +##### Version Note + +**Description:** Provenance information about a given version of the data collection. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"File CB3025.ALL.PDF was removed from any previous datasets and flagged as a study-level file, so that it will accompany all downloads." +``` + +```text +"The data producer provided additional data files." +``` + +```text +"The codebook descriptions of variables TANSUP, EMOSUP, and SOCSUP were corrected." +``` + +#### Complete Version History Examples (with Subfields): + +```yaml +- "Version Number": "V2.1" + "Version Date": "2025-10-03" + "Version Note": "Updated study summary." + +- "Version Number": "V2" + "Version Date": "2023-08-12" + "Version Note": "The data producer provided additional data files." + +- "Version Number": "V1" + "Version Date": "2021-03-01" + "Version Note": "Initial release" +``` + +```yaml +- "Version Number": "V1" + "Version Date": "2024-06-28" + "Version Note": "Initial release" +``` + + +--- + + +### Distributors + +**Description:** The organization(s) responsible for distributing the data collection. + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Organization](#distributors_organization) | Yes | No | Multi-part element; see subfields | Name and other details about the organization that distributes the data collection. | +| [Order](#distributors_order) | Yes | No | Number | The order of importance for the distributors of the data collection. | + + +##### Organization + +**Description:** Name and other details about the organization that distributes the data collection. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Multi-part element; for more information, see the [Organization](#organization) field + + +##### Order + +**Description:** The order of importance for the distributors of the data collection. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Number + +**Usage Notes:** A value of '0' indicates the primary distributor, '1' the second, and so forth. + +**Examples:** + +```text +"0" +``` + +```text +"1" +``` + +```text +"2" +``` + +#### Complete Distributors Examples (with Subfields): + +```yaml +- "Organization": + "Name": "Inter-university Consortium for Political and Social Research" + "Ror": "https://ror.org/02q7mkh03" + "Order": 0 + +- "Organization": + "Name": "GESIS - Leibniz-Institute for the Social Sciences" + "Ror": "https://ror.org/018afyw53" + "Order": 1 +``` + +```yaml +- "Organization": + "Name": "Roper Center for Public Opinion Research" + "Order": 0 +``` + + +--- + + +### Study Number + +**Description:** A unique, numerical value used by ICPSR to identify and track data collections. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Number + +**Usage Notes:** The study number is automatically generated by ICPSR and is unique. Current study numbers are five or six digits, though four digit numbers were once standard and are still acceptable. + +**Examples:** + +```text +"2760" +``` + +```text +"3025" +``` + +```text +"38672" +``` + + +--- + + +### Digital Object Identifier (DOI) + +**Description:** The registered persistent digital object identifier (DOI) associated with the data collection. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** ICPSR Digital Object Identifiers (DOIs) are persistent identifiers provided by [DataCite](https://datacite.org/), a DOI registration agency. Each DOI (such as 'https://doi.org/10.3886/ICPSR39523.v1') has three components: + +1. `https://doi.org` – the DOI resolver, a web address used to look up a DOI and redirect to the resource +1. `10.3886` – the DOI prefix, where '10' identifies the DOI system and '3886' is a unique registrant identifier for ICPSR +1. 'ICPSR', the ICPSR study number, and then the version number (e.g., 'ICPSR39523.v1'). + +The study number is automatically generated by ICPSR and is unique. Current study numbers are five or six digits. Four-digit numbers were once standard and are still acceptable. Additionally, DOIs containing six-digit study numbers prepended with E, for example, https://doi.org/10.3886/E247464V1, were once used for studies self-published at ICPSR. + +Study numbers with less than five digits will have zeroes prepended in the DOI (e.g., Study Number 4 is represented as 10.3886/ICPSR00004'). + +**Examples:** + +```text +"https://doi.org/10.3886/ICPSR300449.V2" +``` + +```text +"https://doi.org/10.3886/ICPSR06425.v1" +``` + + +--- + + +### Citation + +**Description:** The official way to reference the data collection in writing. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Usage Notes:** The Citation is dynamically assembled from other entry fields in this format: PI (list). Title. Distributor (list), Issued Date. DOI. Note: ICPSR 'union catalog' records (i.e., external resource to which ICPSR links as a courtesy) do not have citations. + +**Examples:** + +```text +"Sickmund, Melissa, Hockenberry, Sarah, and Puzzanchera, Charles M. National Juvenile Court Data Archive, United States, 1985-2019. Inter-university Consortium for Political and Social Research [distributor], 2022-07-28. https://doi.org/10.3886/ICPSR38418.v1" +``` + +```text +"Institute of Museum and Library Services. Public Libraries in the United States Survey, 2016-2018. Inter-university Consortium for Political and Social Research [distributor], 2021-10-07. https://doi.org/10.3886/ICPSR37992.v1" +``` + + +--- + + +### Person + +**Description:** A person associated with an ICPSR data collection or service. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Personal Name](#person_name) | Yes | No | Multi-part element; see subfields | The person's name. | +| [ORCID Identifier](#person_orcid) | No | No | Text | The person's Open Researcher and Contributor ID (ORCID). | +| [Affiliation(s)](#person_affiliations) | No | Yes | Multi-part element; see subfields | The person's affiliated organization(s). | +| [Email Address](#person_email) | No | No | Text | The person's email address. | + + +##### Personal Name + +**Description:** The person's name. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +##### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Given Name (First Name)](#person_name_given) | Yes | No | Text | The person's first (given) name, which may include a middle name or initial. | +| [Family Name (Last Name)](#person_name_family) | Yes | No | Text | The person's last (family) name, which may include a suffix (e.g., Jr., Sr., IV). | + + +###### Given Name (First Name) + +**Description:** The person's first (given) name, which may include a middle name or initial. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Miner P." +``` + +```text +"Robert J." +``` + +```text +"Claudia" +``` + + +###### Family Name (Last Name) + +**Description:** The person's last (family) name, which may include a suffix (e.g., Jr., Sr., IV). + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Marchbanks III" +``` + +```text +"Shiller" +``` + +```text +"Goldin" +``` + +#### Complete Personal Name Examples (with Subfields): + +```yaml +"Given Name (First Name)": "Susan B." +"Family Name (Last Name)": "Anthony" +``` + +```yaml +"Given Name (First Name)": "John" +"Family Name (Last Name)": "Doe IV" +``` + + +##### ORCID Identifier + +**Description:** The person's Open Researcher and Contributor ID (ORCID). + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://orcid.org/0009-0006-2316-6486" +``` + +```text +"https://orcid.org/0000-0003-3842-1604" +``` + + +##### Affiliation(s) + +**Description:** The person's affiliated organization(s). + +**Required:** No + +**Repeatable:** Yes + +**Accepted Values:** Multi-part element; for more information, see the [Organization](#organization) field + + +##### Email Address + +**Description:** The person's email address. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"j.doe@example.com" +``` + +#### Complete Person Examples (with Subfields): + +```yaml +"Personal Name": + "Given Name (First Name)": "Robert J." + "Family Name (Last Name)": "Shiller" +"ORCID Identifier": "https://orcid.org/0009-0006-2316-6486" +"Affiliation(s)": +- "Name": "Yale University" + "Ror": "https://ror.org/03v76x132" +- "Name": "MacroMarkets" +``` + +```yaml +"Personal Name": + "Given Name (First Name)": "Claudia" + "Family Name (Last Name)": "Goldin" +"ORCID Identifier": "https://orcid.org/0000-0003-3842-1604" +"Affiliation(s)": +- "Name": "Harvard University" + "Ror": "https://ror.org/03vek6s52" +``` + +```yaml +"Personal Name": + "Given Name (First Name)": "Miner P." + "Family Name (Last Name)": "Marchbanks III" +``` + + +--- + + +### Organization + +**Description:** An organization associated with an ICPSR data collection or service. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Multi-part element; see subfields + +#### Subfields: + +| Property | Required? | Repeatable? | Accepted Values | Description | +|---|---|---|---|---| +| [Organization Name](#organization_name) | Yes | No | Text | The organization's name. | +| [ROR Identifier](#organization_ror) | No | No | Text | The organization's Research Organization Registry (ROR) identifier. | +| [Email Address](#organization_email) | No | No | Text | The organization's email address. | + + +##### Organization Name + +**Description:** The organization's name. + +**Required:** Yes + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"Federal Reserve Bank of St. Louis" +``` + +```text +"University of Michigan" +``` + + +##### ROR Identifier + +**Description:** The organization's Research Organization Registry (ROR) identifier. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"https://ror.org/02q7mkh03" +``` + + +##### Email Address + +**Description:** The organization's email address. + +**Required:** No + +**Repeatable:** No + +**Accepted Values:** Text + +**Examples:** + +```text +"info@example.com" +``` + +#### Complete Organization Examples (with Subfields): + +```yaml +"Organization Name": "Urban Institute" +"ROR Identifier": "https://ror.org/017pz3h73" +"Email Address": "info@urban.institute" +``` + +```yaml +"Organization Name": "Bureau of Justice Statistics" +"ROR Identifier": "https://ror.org/0006s4z66" +``` + +```yaml +"Organization Name": "Internal Revenue Service" +``` + + +--- + +## ICPSR Metadata Schema Version History + +| Date | Version | Note | +|------|---------|------| +| May 11, 2026 | v1 | Initial release and publication of the ICPSR Metadata Schema. | diff --git a/markdown/icpsr_style_guide.md b/markdown/icpsr_style_guide.md index 34122f9..9471a9e 100644 --- a/markdown/icpsr_style_guide.md +++ b/markdown/icpsr_style_guide.md @@ -20,19 +20,6 @@ When referencing ICPSR data collections within metadata records, use the ICPSR i Unless referencing a specific version of an ICPSR data collection, use the unversioned DOI (e.g., https://doi.org/10.3886/ICPSR06425 rather than https://doi.org/10.3886/ICPSR06425.v1) since the unversioned DOI resolves to the latest version of an archived ICPSR data collection. -## Authority Control - -The [ICPSR Personal Name Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) and the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) are the primary authority control sources for names in ICPSR metadata records. - -If names are not present in ICPSR lists, the [Virtual International Authority File](https://viaf.org/) (VIAF) serves as a secondary resource. VIAF is a name authority service that links multiple national authority files (i.e., catalogs of authoritative names such as the [Library of Congress Name Authority File](https://id.loc.gov/authorities/names.html)) into a single international resource. Once the record for an entity is found in VIAF, click on the link next to the American flag to access the Library of Congress entry and use the name in the 100 field (for personal names) or 110 field (for organizational names) of the record. If there are only foreign catalog entries, use of those are acceptable. - -When entering the name of a person or organization, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: - - 1. If the person or organization has published/distributed/sponsored data for ICPSR in the past, use the name as it has been displayed previously within the ICPSR catalog. - 2. If the person or organization is in the [ICPSR Personal Name Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) or the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. - 3. If the person or organization is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). - 4. If the person or organization does not have a VIAF record, consult another authoritative source, such as an organization's website, Google Scholar, or a personal C.V. published on an institutional website. - ## Grammar ### Commas diff --git a/markdown/index.md b/markdown/index.md index 9543ab1..3009c18 100644 --- a/markdown/index.md +++ b/markdown/index.md @@ -6,4 +6,4 @@ The [Inter-university Consortium for Political and Social Research](https://www. This portal provides information about how to use and apply ICPSR metadata. -*Acknowledgements:* Documentation drew heavily from earlier internal ICPSR metadata documentation created by Cole Whiteman, Karen Collamore Sullivan, Carolyn Geda, and Mary Vardigan. Contributors to this portal include: jay winkler, Mike Shallcross, Sanda Ionescu, and Jared Lyle. +*Acknowledgements:* Documentation drew heavily from earlier internal ICPSR metadata documentation created by Cole Whiteman, Karen Collamore Sullivan, Carolyn Geda, and Mary Vardigan. Contributors to this portal include: jay winkler, Mike Shallcross, Sanda Ionescu, Megan Chenoweth, and Jared Lyle. diff --git a/markdown/legacy_schema_intro_text.md b/markdown/legacy_schema_intro_text.md new file mode 100644 index 0000000..02b756c --- /dev/null +++ b/markdown/legacy_schema_intro_text.md @@ -0,0 +1,5 @@ +This metadata schema was used to describe curated data collections at the Inter-university Consortium for Political and Social Research (ICPSR) through approximately 2026. Beginning in 2026, it is being phased out and replaced by [an updated metadata schema](https://icpsr.github.io/metadata/icpsr_metadata_schema/). + +These rules and definitions document ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help users – including data depositors and researchers – understand and interpret ICPSR metadata. + +A machine-actionable version of this schema is available in [JSON Schema](https://github.com/ICPSR/metadata/blob/main/schema/icpsr_study_schema.json) format. \ No newline at end of file diff --git a/resources/key.md b/markdown/legacy_schema_key.md similarity index 89% rename from resources/key.md rename to markdown/legacy_schema_key.md index 80b1047..18c4a65 100644 --- a/resources/key.md +++ b/markdown/legacy_schema_key.md @@ -1,6 +1,6 @@ -## Key for Metadata Element Entries +## Key for Legacy ICPSR Metadata Schema Entries -Full information for each ICPSR study metadata element includes the following fields: +Full information for each legacy ICPSR study metadata element includes the following fields: - **Description:** A short description of the metadata element and the information it is intended to convey. - **Required:** Indicates whether the metadata element is mandatory ("Yes") or optional ("No"). Required elements must include at least one value. diff --git a/markdown/version_history.md b/markdown/legacy_schema_version_history.md similarity index 79% rename from markdown/version_history.md rename to markdown/legacy_schema_version_history.md index 87f5464..918bb6f 100644 --- a/markdown/version_history.md +++ b/markdown/legacy_schema_version_history.md @@ -1,9 +1,9 @@ -## ICPSR Metadata Schema Version History +## ICPSR Legacy Metadata Schema Version History | Date | Version | Note | |------|---------|------| | April 14, 2026 | v1.3 | Updated ICPSR input guidance for Geographic Coverage Area. | | April 11, 2025 | v1.2 | Updated field definitions to improve clarity. | | June 28, 2024 | v1.1 | Removed guidance regarding null entries for National Institute of Justice studies. Several fields previously required "None" when otherwise a field would be left blank. Updated internal guidance for 'external source id' and 'funding purpose' elements. Added 'study number' and distributor 'order' elements to address earlier oversights. | -| Oct. 30, 2023 | v1 | Initial release and publication of the ICPSR Metadata Schema. | +| Oct. 30, 2023 | v1 | Initial release and publication of the legacy ICPSR Metadata Schema. | diff --git a/markdown/schema_intro_text.md b/markdown/schema_intro_text.md new file mode 100644 index 0000000..c9c4c9b --- /dev/null +++ b/markdown/schema_intro_text.md @@ -0,0 +1,5 @@ +This metadata schema is used to describe data collections at the Inter-university Consortium for Political and Social Research (ICPSR) after 2026. + +These rules and definitions document ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help users – including data depositors and researchers – understand and interpret ICPSR metadata. + +Machine-actionable copies of metadata field definitions are also available in [JSON Schema](https://github.com/ICPSR/metadata/tree/main/rde_schema/property_bank) format. \ No newline at end of file diff --git a/markdown/schema_key.md b/markdown/schema_key.md new file mode 100644 index 0000000..945b863 --- /dev/null +++ b/markdown/schema_key.md @@ -0,0 +1,11 @@ +## Key for ICPSR Metadata Schema Entries + +Full information for each ICPSR study metadata element includes the following fields: + +- **Description:** A short description of the metadata element and the information it is intended to convey. +- **Required:** Indicates whether the metadata element is mandatory ("Yes") or optional ("No"). Required elements must include at least one value. +- **Repeatable:** Indicates whether the metadata element may be repeated ("Yes") or if it may only occur once ("No"). +- **Accepted values:** The type of values that may be used with the metadata element; options include text (with additional requirements, such as date formatting, noted when present) and numbers. Multi-part metadata elements have accepted value information provided in entries for individual subelements. +- **Usage Notes:** Additional information about the nature, scope, and conventions for values that may be added to the metadata element. +- **Examples:** Examples of valid values for the metadata element. + \ No newline at end of file diff --git a/markdown/schema_version_history.md b/markdown/schema_version_history.md new file mode 100644 index 0000000..6123bb3 --- /dev/null +++ b/markdown/schema_version_history.md @@ -0,0 +1,6 @@ +## ICPSR Metadata Schema Version History + +| Date | Version | Note | +|------|---------|------| +| May 11, 2026 | v1 | Initial release and publication of the ICPSR Metadata Schema. | + diff --git a/rde_schema/notes/collection_dates_time_frame.yaml b/rde_schema/notes/collection_dates_time_frame.yaml new file mode 100644 index 0000000..ba6747a --- /dev/null +++ b/rde_schema/notes/collection_dates_time_frame.yaml @@ -0,0 +1,7 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/collection_dates_time_frame + usageNotes: | + The textual description ('time frame') is used to add context to the Collection Date when multiple time periods exist (e.g., to describe different study waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. + + The textual description should not simply restate the time period in words. For example, if the Collection Date is 2020-01, the Time Frame should not be 'January 2020'. diff --git a/rde_schema/notes/doi.yaml b/rde_schema/notes/doi.yaml new file mode 100644 index 0000000..9a67e29 --- /dev/null +++ b/rde_schema/notes/doi.yaml @@ -0,0 +1,13 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/doi + usageNotes: | + ICPSR Digital Object Identifiers (DOIs) are persistent identifiers provided by [DataCite](https://datacite.org/), a DOI registration agency. Each DOI (such as 'https://doi.org/10.3886/ICPSR39523.v1') has three components: + + 1. `https://doi.org` – the DOI resolver, a web address used to look up a DOI and redirect to the resource + 1. `10.3886` – the DOI prefix, where '10' identifies the DOI system and '3886' is a unique registrant identifier for ICPSR + 1. 'ICPSR', the ICPSR study number, and then the version number (e.g., 'ICPSR39523.v1'). + + The study number is automatically generated by ICPSR and is unique. Current study numbers are five or six digits. Four-digit numbers were once standard and are still acceptable. Additionally, DOIs containing six-digit study numbers prepended with E, for example, https://doi.org/10.3886/E247464V1, were once used for studies self-published at ICPSR. + + Study numbers with less than five digits will have zeroes prepended in the DOI (e.g., Study Number 4 is represented as 10.3886/ICPSR00004'). diff --git a/rde_schema/notes/funding_sources_organization.yaml b/rde_schema/notes/funding_sources_organization.yaml new file mode 100644 index 0000000..cbb11fe --- /dev/null +++ b/rde_schema/notes/funding_sources_organization.yaml @@ -0,0 +1,16 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/funding_sources_organization + usageNotes: | + When entering the name of a funding organization: + + * Whenever possible, enter the organization’s name as it appears in the [Research Organization Registry](https://ror.org/) (ROR). + * If the funding organization is a department or subunit of an organization that appears in ROR, but does not have its own ROR ID, enter the organization name as it appears in ROR, followed by a period and the name of the department or subunit. + * If the organization doesn't have a ROR ID, use its full name and avoid acronyms. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If the organization has funded data collections with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * Except for principal investigators that are departments or subunits of organizations in ROR, do not prepend the organization's name with its institutional hierarchy. For example, enter "National Institute on Aging" instead of "United States Department of Health and Human Services. National Institutes of Health. National Institute on Aging". + * If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + + The Principal Investigator's home institution does not need to be listed as a funding agency unless the PI provides a grant number (or other award information) or makes a specific request. diff --git a/rde_schema/notes/geographic_coverage_areas.yaml b/rde_schema/notes/geographic_coverage_areas.yaml new file mode 100644 index 0000000..0943780 --- /dev/null +++ b/rde_schema/notes/geographic_coverage_areas.yaml @@ -0,0 +1,34 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/geographic_coverage_areas + usageNotes: | + When choosing Geographic Coverage Areas: + + * Select the country, state, city, county, region, or continent covered by the study. + * Spell out place names completely instead of using acronyms. For example, enter "United States" instead of "USA." + * Type at least four characters to see matches. + * Choose only the narrowest level of geographic coverage. For example, if you select "Los Angeles, California, United States," do not also add "California, United States" and "United States." + * For studies with participants from around the world or that are applicable everywhere, select "Earth." + + Geographic locations are drawn from the GeoNames geographical database. Source: [https://www.geonames.org/](https://www.geonames.org/). Allowable feature codes include: + + * From Feature Class A (country, state, region,... – e.g., Administrative Divisions): + * ADM1 (first-order administrative division – e.g., US states, Canadian provinces, etc.) + * ADM2 (second-order administrative division – e.g. US counties) + * PCLI (independent political entity – e.g., countries) + * PCLD (dependent political entity – e.g., Puerto Rico and Guam) + * PCLF (freely associated state – e.g., Palau, Micronesia, and Marshall Islands) + * PCLH (historical political entity – e.g., former entities like Yugoslavia and USSR) + * PCLS (semi-independent political entity – e.g., Palestine, Macao, and Hong Kong) + * PCL (political entity – e.g., Guernsey, Jersey, and Isle of Man) + * TERR (territory – e.g., American Samoa, Svalbard and Jan Mayen, etc.) + * ZN (zone – e.g., European Union, Commonwealth of Nations, and NATO) + * From Feature Class P (city, village,... – e.g., Populated Places) + * PPLG (seat of government of a political entity) + * PPLC (capital of a political entity) + * PPLA (seat of a first-order administrative division) + * PPLA2 (seat of a second-order administrative division) + * PPL (populated place) + * From Feature Class L (parks,area, ..) + * RGN (region) + * CONT (continent) diff --git a/rde_schema/notes/principal_investigators_organization.yaml b/rde_schema/notes/principal_investigators_organization.yaml new file mode 100644 index 0000000..4d7d0c4 --- /dev/null +++ b/rde_schema/notes/principal_investigators_organization.yaml @@ -0,0 +1,16 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/principal_investigators_organization + usageNotes: | + When entering the name of a principal investigator that is an organization: + + * Whenever possible, enter the organization name as it appears in the [Research Organization Registry](https://ror.org/) (ROR). + * If the principal investigator is a department or subunit of an organization that appears in ROR, but does not have its own ROR ID, enter the organization name as it appears in ROR, followed by a period and the name of the department or subunit. + * If the organization doesn’t have a ROR ID, use its full name and avoid acronyms. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If the PI has published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * Except for principal investigators that are departments or subunits of organizations in ROR, do not prepend the organization's name with its institutional hierarchy. For example, enter "National Institute on Aging," not "United States Department of Health and Human Services. National Institutes of Health. National Institute on Aging." + * If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + + When selecting a ROR ID, choose the most specific applicable ROR (for example, Inter-university Consortium for Political and Social Research, not University of Michigan). \ No newline at end of file diff --git a/rde_schema/notes/principal_investigators_person.yaml b/rde_schema/notes/principal_investigators_person.yaml new file mode 100644 index 0000000..bdd0ba7 --- /dev/null +++ b/rde_schema/notes/principal_investigators_person.yaml @@ -0,0 +1,34 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/principal_investigators_person + usageNotes: | + When entering the name of a principal investigator who is a person: + + * Enter a specific and unique name, for example, by including full names and middle initials where appropriate. + * Follow commonly accepted, language-appropriate practices for capitalization and punctuation. + * Within the bounds of these first two principles, follow the PI’s precedent for how their name appears in print. + + To determine the preferred form of name to appear in ICPSR’s metadata catalog, consult the following authority sources, in this order. + * ICPSR's metadata catalog. If the PI has published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The PI’s curriculum vitae published on an institutional website. + * The [Virtual International Authority File](https://viaf.org/en) (VIAF). + * The PI’s [Open Researcher and Contributor Identifier](https://orcid.org/) (ORCID) record. + * The PI’s Google Scholar profile. + * The PI’s other published works. + * The PI’s bio on their organization’s website. + + The given (i.e., 'first') name may include the middle name or initial. If the person only uses an inital for the given name, do not include a space between first and middle initials (e.g., 'E.V.'). The family (i.e., 'last') name can include any suffixes (such as 'II' or 'Jr.'). Abbreviations are discouraged (especially 'et al.'). + + Whenever possible, add an ORCID for each principal investigator. + + When entering a principal investigator's affiliation(s): + * Enter the PI's affiliation as it appears in the Research Organization Registry (ROR). + * If the organization doesn't have a ROR ID, enter its full name, avoid acronyms, and do not include departments or colleges. Consult the following sources authority sources to determine the preferred name form. + * ICPSR’s metadata catalog. If other PIs affiliated with this organization have published data with ICPSR before, especially curated data, use the name as it appears in previous studies. + * The organization's website. + * The Virtual International Authority File (VIAF). + * Enter a PI's affiliation at the time the research was conducted. If the organization's name has changed over time, enter the name that applied at the time the research was conducted. + * If a PI's affiliation has both English and non-English name forms in ROR or VIAF, select a preferred English language form. + * If a PI's organizational affiliation is not known, use the term 'Unknown' in the PI Organization element. + * If multiple PIs (people) are affiliated with the same organization, include the affiliated organization's name for each person. + * If a PI has multiple affiliations, enter each organization as its own affiliation. \ No newline at end of file diff --git a/rde_schema/notes/sampling_procedures.yaml b/rde_schema/notes/sampling_procedures.yaml new file mode 100644 index 0000000..4882977 --- /dev/null +++ b/rde_schema/notes/sampling_procedures.yaml @@ -0,0 +1,7 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/sampling_procedures + usageNotes: | + The sample is a selection out of the universe of all possible relevant cases (e.g., adults in the United States, housing units in three counties of Michigan, etc.) that could have been included in the data collection. Note that some studies, such as censuses, do not utilize samples but include all members of the universe. + + This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV SamplingProcedure [https://rdf-vocabulary.ddialliance.org/ddi-cv/SamplingProcedure/1.1.4/SamplingProcedure.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/SamplingProcedure/1.1.4/SamplingProcedure.html) \ No newline at end of file diff --git a/rde_schema/notes/smallest_geographic_unit.yaml b/rde_schema/notes/smallest_geographic_unit.yaml new file mode 100644 index 0000000..a0bfacf --- /dev/null +++ b/rde_schema/notes/smallest_geographic_unit.yaml @@ -0,0 +1,9 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/smallest_geographic_unit + usageNotes: | + Smallest Geographic Unit is intended to represent specific, known geography – e.g., county, census district, Zip code, electoral district, etc. – that is represented by a variable. + + If the data do not include a geographic variable by which the data can be analyzed, this element is not indicated. If all the cases are from a single state, but the cases are not subdivided geographically within that state, then 'state' is not indicated. + + If there is a variable indicating which testing site a survey was taken at, but the locations of the testing sites were masked by the PI, this element is likely not indicated. \ No newline at end of file diff --git a/rde_schema/notes/summary.yaml b/rde_schema/notes/summary.yaml new file mode 100644 index 0000000..45a968d --- /dev/null +++ b/rde_schema/notes/summary.yaml @@ -0,0 +1,7 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/summary + usageNotes: | + The Summary may include information about the different parts of the data collection not adequately conveyed by the Fileset names or found elsewhere in the metadata. Other important components include a listing of major variables or categories of variables (with examples) as well as an indication of the data collection's unit of analysis (i.e., who or what is being studied: individuals, housing units, courts, criminal acts, etc.). Most often the unit of analysis is the individual; where it is not, it is particularly important to make this clear. + + The Summary is written in the third person and avoids attempting to address issues of how the data might be used, who might be interested in the data, or any evaluative comments about the worth or usefulness of the data collection. The Summary uses past tense when describing the process of collecting the data and present tense when necessary, such as when describing the data (e.g., 'The MIDUS Refresher collection is split into two datasets.'). Numerals are used instead of spelling them out; if a number is spelled out for emphasis, the number is attached in parentheses – e.g. 'Two thousand (2,000)'. diff --git a/rde_schema/notes/time_periods_time_frame.yaml b/rde_schema/notes/time_periods_time_frame.yaml new file mode 100644 index 0000000..e34df61 --- /dev/null +++ b/rde_schema/notes/time_periods_time_frame.yaml @@ -0,0 +1,7 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/notes/time_periods_time_frame + usageNotes: | + The textual description ('time frame') is used to add context to the Time Period when multiple time periods exist (e.g., to describe different waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. + + The textual description should not simply restate the time period in words. For example, if the start and end dates for Time Period are 2020-01, the associated Time Frame should not be 'January 2020'. diff --git a/schema/yaml/title.yaml b/rde_schema/notes/title.yaml similarity index 95% rename from schema/yaml/title.yaml rename to rde_schema/notes/title.yaml index 4939296..9369103 100644 --- a/schema/yaml/title.yaml +++ b/rde_schema/notes/title.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/title?version=v1 + $id: https://schemas.icpsr.umich.edu/notes/title usageNotes: | The Title includes three essential parts: the title proper, the geography, and the time period. @@ -26,7 +26,7 @@ * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. - * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has “National” in the title, or a similar word specific to that country. + * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has "National" in the title, or a similar word specific to that country. Time Period: diff --git a/rde_schema/property_bank/ada_accessibility.json b/rde_schema/property_bank/ada_accessibility.json new file mode 100644 index 0000000..553733a --- /dev/null +++ b/rde_schema/property_bank/ada_accessibility.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/ada_accessibility", + "title": "ADA Accessibility", + "description": "Indicates whether the data collection is ADA accessible, conforming to WCAG 2.1 AA standards, or qualifies for the ADA archival exception.", + "controlledVocab": "adaAccessibility", + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "ADA Accessible", + "ADA Archival" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "ada.accessible", + "ada.archival" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/adaAccessibility/terms/ada.accessible", + "/api/v1/vocab-terms/adaAccessibility/terms/ada.archival" + ] + } + }, + "required": ["label", "code", "uri"], + "examples": [ + { + "label": "ADA Accessible", + "code": "ada.accessible", + "uri": "/api/v1/vocab-terms/adaAccessibility/terms/ada.accessible" + }, + { + "label": "ADA Archival", + "code": "ada.archival", + "uri": "/api/v1/vocab-terms/adaAccessibility/terms/ada.archival" + } + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/alternate_titles.json b/rde_schema/property_bank/alternate_titles.json new file mode 100644 index 0000000..406d6bc --- /dev/null +++ b/rde_schema/property_bank/alternate_titles.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/alternate_titles", + "title": "Alternate Titles", + "description": "The alternate name(s) or acronym(s) commonly used to refer to the data collection.", + "usageNotes": "Alternate Title often takes the form of a shortened (by abbreviation or acronym) version of the official title.", + "type": "array", + "items": { "type": "string" }, + "examples": [ + ["Add Health Parent Study"], + ["FACES 2009"], + ["Survey of Consumers"], + ["Eurobarometer 85.2"] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/citation.json b/rde_schema/property_bank/citation.json new file mode 100644 index 0000000..4684515 --- /dev/null +++ b/rde_schema/property_bank/citation.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/citation", + "title": "Citation", + "description": "The official way to reference the data collection in writing.", + "type": "string", + "usageNotes": "The Citation is dynamically assembled from other entry fields in this format: PI (list). Title. Distributor (list), Issued Date. DOI. Note: ICPSR 'union catalog' records (i.e., external resource to which ICPSR links as a courtesy) do not have citations.", + "examples": [ + "Sickmund, Melissa, Hockenberry, Sarah, and Puzzanchera, Charles M. National Juvenile Court Data Archive, United States, 1985-2019. Inter-university Consortium for Political and Social Research [distributor], 2022-07-28. https://doi.org/10.3886/ICPSR38418.v1", + "Institute of Museum and Library Services. Public Libraries in the United States Survey, 2016-2018. Inter-university Consortium for Political and Social Research [distributor], 2021-10-07. https://doi.org/10.3886/ICPSR37992.v1" + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/collection_dates.json b/rde_schema/property_bank/collection_dates.json new file mode 100644 index 0000000..05cbe97 --- /dev/null +++ b/rde_schema/property_bank/collection_dates.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/collection_dates", + "title": "Collection Dates", + "description": "The date(s) data collection took place.", + "type": "array", + "items": { + "type": "object", + "properties": { + "start_date": { + "title": "Start Date", + "description": "The start date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces.", + "type": "string", + "examples": ["2000", "2019-10", "2021-03-01"] + }, + "end_date": { + "title": "End Date", + "description": "The end date of the data collection period. Must be in YYYY-MM-DD, YYYY-MM, or YYYY format with no spaces.", + "type": "string", + "examples": ["2000", "2019-10", "2021-03-01"] + }, + "time_frame": { + "title": "Time Frame", + "description": "An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present.", + "type": "string", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/collection_dates_time_frame#/usageNotes" }, + "examples": [ "Fall 2001", "Student data"] + } + }, + "required": ["start_date", "end_date"] + }, + "minItems": 1, + "examples": [ + [ + { + "start_date": "2018", + "end_date": "2018", + "time_frame": "Wave 1" + }, + { + "start_date": "2020-10", + "end_date": "2020-10", + "time_frame": "Wave 2" + } + ], + [ + { + "start_date": "2003-01-01", + "end_date": "2003-12-31" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/collection_modes.json b/rde_schema/property_bank/collection_modes.json new file mode 100644 index 0000000..fcac924 --- /dev/null +++ b/rde_schema/property_bank/collection_modes.json @@ -0,0 +1,58 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/collection_modes", + "title": "Collection Modes", + "description": "The method(s) or procedure(s) used to collect the data, such as an interview or experiment.", + "usageNotes": "This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV ModeOfCollection [https://rdf-vocabulary.ddialliance.org/ddi-cv/ModeOfCollection/4.0.3/ModeOfCollection.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/ModeOfCollection/4.0.3/ModeOfCollection.html).", + "controlledVocab": "collectionModes", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Face-to-face interview: Computer-assisted (CAPI/CAMI)", + "Measurements and tests", + "Computer-based observation" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": ["Interview.FaceToFace.CAPIorCAMI", "MeasurementsAndTests", "Observation.ComputerBased"] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": ["/api/v1/vocab-terms/collectionModes/terms/Interview.FaceToFace.CAPIorCAMI"] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Face-to-face interview: Computer-assisted (CAPI/CAMI)", + "code": "Interview.FaceToFace.CAPIorCAMI", + "uri": "/api/v1/vocab-terms/collectionModes/terms/Interview.FaceToFace.CAPIorCAMI" + } + ], + [ + { + "label": "Measurements and tests", + "code": "MeasurementsAndTests", + "uri": "/api/v1/vocab-terms/collectionModes/terms/MeasurementsAndTests" + }, + { + "label": "Computer-based observation", + "code": "Observation.ComputerBased", + "uri": "/api/v1/vocab-terms/collectionModes/terms/Observation.ComputerBased" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/data_management_plan.json b/rde_schema/property_bank/data_management_plan.json new file mode 100644 index 0000000..cba6b73 --- /dev/null +++ b/rde_schema/property_bank/data_management_plan.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/data_management_plan", + "title": "Data Management Plan", + "description": "A link to the data management plan (preferably a persistent identifier such as a DOI).", + "type": "string", + "format": "uri", + "examples": [ + "https://doi.org/10.48321/D1EA6EF78D", "https://rdm.mcmaster.ca/dmps/promoting-healthy-families-data-management-plan" + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/data_source_types.json b/rde_schema/property_bank/data_source_types.json new file mode 100644 index 0000000..727556e --- /dev/null +++ b/rde_schema/property_bank/data_source_types.json @@ -0,0 +1,65 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/data_source_types", + "title": "Data Source Types", + "description": "The source(s) of the data as collected by the Principal Investigators.", + "usageNotes": "People, things, and other data can all be Data Source Types. This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV DataSourceType [https://rdf-vocabulary.ddialliance.org/ddi-cv/DataSourceType/1.0.2/DataSourceType.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/DataSourceType/1.0.2/DataSourceType.html).", + "controlledVocab": "dataSourceTypes", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Registers/Records/Accounts: Medical/Clinical", + "Events/Interactions", + "Research data: Published" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "RegistersRecordsAccounts.MedicalClinical", + "EventsInteractions", + "ResearchData.Published"] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/dataSourceTypes/terms/RegistersRecordsAccounts.MedicalClinical", + "/api/v1/vocab-terms/dataSourceTypes/terms/EventsInteractions", + "/api/v1/vocab-terms/dataSourceTypes/terms/ResearchData.Published" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Registers/Records/Accounts: Medical/Clinical", + "code": "RegistersRecordsAccounts.MedicalClinical", + "uri": "/api/v1/vocab-terms/dataSourceTypes/terms/RegistersRecordsAccounts.MedicalClinical" + }, + { + "label": "Events/Interactions", + "code": "EventsInteractions", + "uri": "/api/v1/vocab-terms/dataSourceTypes/terms/EventsInteractions" + } + ], + [ + { + "label": "Research data: Published", + "code": "ResearchData.Published", + "uri": "/api/v1/vocab-terms/dataSourceTypes/terms/ResearchData.Published" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/distributors.json b/rde_schema/property_bank/distributors.json new file mode 100644 index 0000000..29662fb --- /dev/null +++ b/rde_schema/property_bank/distributors.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/distributors", + "title": "Distributors", + "description": "The organization(s) responsible for distributing the data collection.", + "type": "array", + "items": { + "type": "object", + "properties": { + "organization": { + "$ref": "https://archive.icpsr.umich.edu/schema/property_banks/organization/version/1", + "title": "Organization", + "description": "Name and other details about the organization that distributes the data collection." + }, + "order": { + "title": "Order", + "description": "The order of importance for the distributors of the data collection.", + "type": "integer", + "usageNotes": "A value of '0' indicates the primary distributor, '1' the second, and so forth.", + "examples": [0,1,2] + } + }, + "required": ["organization", "order"] + }, + "minItems": 1, + "examples": [ + [ + { + "organization": { + "name": "Inter-university Consortium for Political and Social Research", + "ror": "https://ror.org/02q7mkh03" + }, + "order": 0 + }, + { + "organization": { + "name": "GESIS - Leibniz-Institute for the Social Sciences", + "ror": "https://ror.org/018afyw53" + }, + "order": 1 + } + ], + [ + { + "organization": { + "name": "Roper Center for Public Opinion Research" + }, + "order": 0 + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/doi.json b/rde_schema/property_bank/doi.json new file mode 100644 index 0000000..3cab022 --- /dev/null +++ b/rde_schema/property_bank/doi.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/doi", + "title": "Digital Object Identifier (DOI)", + "description": "The registered persistent digital object identifier (DOI) associated with the data collection.", + "type": "string", + "format": "uri", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/doi#/usageNotes" }, + "examples": [ + "https://doi.org/10.3886/ICPSR300449.V2", + "https://doi.org/10.3886/ICPSR06425.v1" + ] +} diff --git a/rde_schema/property_bank/external_data_sources.json b/rde_schema/property_bank/external_data_sources.json new file mode 100644 index 0000000..c8aa906 --- /dev/null +++ b/rde_schema/property_bank/external_data_sources.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/external_data_sources", + "title": "External Data Sources", + "description": "The source of the data, when that source is external to the data collection and can be independently cited.", + "type": "array", + "items": { + "type": "string" + }, + "usageNotes": "External data sources can include websites, datasets, books, journal articles, and other sources. Each source includes at minimum the title, author, publication year, journal (if applicable), and DOI or URL for online sources. Any citation format is accepted.", + "examples": [ + ["'Voting Scores.' Congressional Quarterly Almanac 33 (1977), 487-498"], + ["Multi-Resolution Land Characteristics Consortium. \"National Land Cover Database (CONUS), All Years,\" 2016. https://www.mrlc.gov/data/nlcd-land-cover-conus-all-years"], + ["Data file 1: United States Census Bureau (2010). TIGER/Line shapefiles, 2010 census tracts (2010 version) [Data set]. https://www2.census.gov/geo/tiger/TIGER2010/TRACT/2010/tl_2010_01_tract10.zip"] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/funding_sources.json b/rde_schema/property_bank/funding_sources.json new file mode 100644 index 0000000..d0f0c9c --- /dev/null +++ b/rde_schema/property_bank/funding_sources.json @@ -0,0 +1,100 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/funding_sources", + "title": "Funding Sources", + "description": "The sources of funding that supported the data collection.", + "type": "array", + "items": { + "type": "object", + "properties": { + "organization": { + "$ref": "https://archive.icpsr.umich.edu/schema/property_banks/organization/version/1", + "title": "Funding Organization", + "description": "Name and other details about the organization that provided the funding.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/funding_sources_organization#/usageNotes" } + }, + "grants": { + "title": "Funding Awards", + "description": "Identifiers and other details about financial support for the data collection.", + "usageNotes": "Whenever possible, provide a grant number for the funding award. If one exists, you can also provide a URL, preferably a persistent one like a digital object identifier (DOI).", + "type": "array", + "items": { + "type": "object", + "properties": { + "grant_number": { + "title": "Funding Identifier", + "description": "The unique identifier for the funding (e.g., ABC-0123456).", + "type": "string", + "examples": [ + "SES-1835721", + "MDR-8550085", + "40791" + ] + }, + "grant_uri": { + "title": "Funding URL", + "description": "A unique identifier (URL), preferably a persistent one like a DOI, linking to a landing page with funding information.", + "type": "string", + "format": "uri", + "examples": [ + "https://doi.org/10.35802/212242" + ] + } + }, + "required": ["grant_number"] + } + }, + "order": { + "title": "Order", + "description": "Internal ICPSR field used to determine the order of importance for the funders associated with the data collection.", + "type": "integer", + "examples": [ + 0, + 1, + 2 + ] + } + }, + "required": ["organization", "order"] + }, + "examples": [ + [ + { + "organization": { + "name": "Robert Wood Johnson Foundation", + "ror": "https://ror.org/02ymmdj85" + }, + "grants": [ + { + "grant_number": "MDR-8550085" + }, + { + "grant_number": "MDR-8550204" + } + ], + "order": 0 + }, + { + "organization": { + "name": "Bureau of Justice Statistics", + "ror": "https://ror.org/0006s4z66" + }, + "grants": [ + { + "grant_number": "SES-1835721", + "grant_uri": "https://doi.org/10.35802/000000" + } + ], + "order": 1 + } + ], + [ + { + "organization": { + "name": "Acme Foundation" + }, + "order": 0 + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/general_data_formats.json b/rde_schema/property_bank/general_data_formats.json new file mode 100644 index 0000000..bf1cba6 --- /dev/null +++ b/rde_schema/property_bank/general_data_formats.json @@ -0,0 +1,61 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/general_data_formats", + "title": "General Data Formats", + "description": "The file format types present in the data collection.", + "usageNotes": "This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV GeneralDataFormat [https://rdf-vocabulary.ddialliance.org/ddi-cv/GeneralDataFormat/2.0.3/GeneralDataFormat.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/GeneralDataFormat/2.0.3/GeneralDataFormat.html).", + "controlledVocab": "generalDataFormats", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Text", + "Still image", + "Numeric" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "Text", + "StillImage", + "Numeric" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string" + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Text", + "code": "Text", + "uri": "/api/v1/vocab-terms/generalDataFormats/terms/Text" + }, + { + "label": "Still image", + "code": "StillImage", + "uri": "/api/v1/vocab-terms/generalDataFormats/terms/StillImage" + } + ], + [ + { + "label": "Numeric", + "code": "Numeric", + "uri": "/api/v1/vocab-terms/generalDataFormats/terms/Numeric" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/geographic_coverage_areas.json b/rde_schema/property_bank/geographic_coverage_areas.json new file mode 100644 index 0000000..f3ed10d --- /dev/null +++ b/rde_schema/property_bank/geographic_coverage_areas.json @@ -0,0 +1,123 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/geographic_coverage_areas", + "title": "Geographic Coverage Areas", + "description": "The geographic locations where the data refer or are related.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/geographic_coverage_areas#/usageNotes" }, + "controlledVocab": "geoNames", + "type": "array", + "items": { + "type": "object", + "properties": { + "city": { + "title": "City", + "description": "A town, city, or similar populated place covered in the data collection", + "type": "string", + "examples": ["Ann Arbor", "Hanover", "Chongqing"] + }, + "county": { + "title": "County", + "description": "A United States county or similar administrative area covered in the data collection", + "type": "string", + "examples": ["Monroe County", "Washtenaw County", "Cuyahoga County"] + }, + "state": { + "title": "State", + "description": "A state, province, canton or similar political entity covered in the data collection", + "type": "string", + "examples": ["Michigan", "Manitoba", "Yunnan"] + }, + "country": { + "title": "Country", + "description": "A country covered in the data collection", + "type": "string", + "examples": ["United States", "China", "Ghana"] + }, + "region": { + "title": "Region", + "description": "An area distinguished by one or more observable physical or cultural characteristics that is covered in the data collection.", + "type": "string", + "examples": ["Sub-Saharan Africa", "Eastern Europe", "Siberia"] + }, + "continent": { + "title": "Continent", + "description": "A continent covered in the data collection", + "type": "string", + "examples": ["Africa", "Asia", "South America"] + }, + "other_area": { + "title": "Other Geographic Area", + "description": "An area covered in the data collection that cannot be represented using the defined categories above or matched to an appropriate GeoNames record.", + "type": "string", + "usageNotes": "Use this for user-provided terms, loosely defined geographic concepts, GeoNames feature types not covered by city/county/state/country/region/continent, or historical geographic entities (e.g., Prussia) not represented in GeoNames.", + "examples": ["Global", "Eurasia", "13 U.S. states in 3 regions"] + }, + "uri": { + "title": "URI", + "description": "A local unique identifier for the geographic coverage area.", + "type": "string", + "format": "uri", + "examples": [ "/api/v1/vocab-terms/geoNames/terms/6252001", "/api/v1/vocab-terms/geoNames/terms/6269554" ] + }, + "externalURI": { + "title": "External URI", + "description": "The GeoNames unique identifier for the geographic coverage area.", + "type": "string", + "format": "uri", + "examples": [ "https://sws.geonames.org/4990729/", "https://sws.geonames.org/6269554" ] + } + } + }, + "examples": [ + [ + { + "city": "Cleveland", + "state": "Ohio", + "country": "United States", + "continent": "North America", + "externalURI": "https://sws.geonames.org/5150529", + "uri": "/api/v1/vocab-terms/geoNames/terms/5150529" + }, + { + "county": "Washtenaw County", + "state": "Michigan", + "country": "United States", + "continent": "North America", + "externalURI": "https://sws.geonames.org/5014120", + "uri": "/api/v1/vocab-terms/geoNames/terms/5014120" + }, + { + "state": "Pennsylvania", + "country": "United States", + "continent": "North America", + "externalURI": "https://sws.geonames.org/5206379", + "uri": "/api/v1/vocab-terms/geoNames/terms/5206379" + } + ], + [ + { + "country": "Germany", + "continent": "Europe", + "externalURI": "https://sws.geonames.org/2921044", + "uri": "/api/v1/vocab-terms/geoNames/terms/2921044" + }, + { + "continent": "Africa", + "externalURI": "https://sws.geonames.org/6255146", + "uri": "/api/v1/vocab-terms/geoNames/terms/6255146" + } + ], + [ + { + "other_area": "Global", + "externalURI": "https://sws.geonames.org/6295630", + "uri": "/api/v1/vocab-terms/geoNames/terms/6295630" + } + ], + [ + { + "other_area": "13 U.S. states in 3 regions" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/icpsr_subject_terms.json b/rde_schema/property_bank/icpsr_subject_terms.json new file mode 100644 index 0000000..8cb07d1 --- /dev/null +++ b/rde_schema/property_bank/icpsr_subject_terms.json @@ -0,0 +1,57 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/icpsr_subject_terms", + "title": "ICPSR Subject Terms", + "description": "A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection.", + "usageNotes": "This controlled vocabulary was taken from the ICPSR Subject Terms Thesaurus. Source: [https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001).", + "controlledVocab": "subjectTerms", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "ICPSR Subject Term", + "description": "A human-readable form of the subject term.", + "type": "string", + "examples": ["employment", "marriage", "recidivism"] + }, + "code": { + "title": "ICPSR Subject Term Code", + "description": "A machine-readable/-actionable form of the subject term.", + "type": "string", + "examples": ["25220", "26180", "26961"] + }, + "uri": { + "title": "ICPSR Subject Term URI", + "description": "The URI for the subject term.", + "type": "string", + "examples": [ + "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/25220", + "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/26180" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "lobbying", + "code": "26131", + "uri": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/26131" + }, + { + "label": "age", + "code": "24123", + "uri": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/24123" + } + ], + [ + { + "label": "happiness", + "code": "25624", + "uri": "https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10001/terms/25624" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/jel_classifications.json b/rde_schema/property_bank/jel_classifications.json new file mode 100644 index 0000000..734b61b --- /dev/null +++ b/rde_schema/property_bank/jel_classifications.json @@ -0,0 +1,66 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/jel_classifications", + "title": "Journal of Economic Literature (JEL) Classification Codes", + "description": "Classification codes used to categorize economic research.", + "usageNotes": "This controlled vocabulary was taken from the American Economic Association's JEL Classifications Codes. Source: [https://www.aeaweb.org/jel/guide/jel.php](https://www.aeaweb.org/jel/guide/jel.php)", + "controlledVocab": "jelClassifications", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Relation of Economics to Other Disciplines", + "History of Economic Thought, Methodology, and Heterodox Approaches", + "Economic History: Financial Markets and Institutions: U.S.; Canada: 1913-" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "A12", + "B00", + "N22" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the JEL classification code.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/jelClassifications/terms/A12", + "/api/v1/vocab-terms/jelClassifications/terms/B00", + "/api/v1/vocab-terms/jelClassifications/terms/N22" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Relation of Economics to Other Disciplines", + "code": "A12", + "uri": "/api/v1/vocab-terms/jelClassifications/terms/A12" + }, + { + "label": "History of Economic Thought, Methodology, and Heterodox Approaches", + "code": "B00", + "uri": "/api/v1/vocab-terms/jelClassifications/terms/B00" + } + ], + [ + { + "label": "Economic History: Financial Markets and Institutions: U.S.; Canada: 1913-", + "code": "N22", + "uri": "/api/v1/vocab-terms/jelClassifications/terms/N22" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/license.json b/rde_schema/property_bank/license.json new file mode 100644 index 0000000..8c99073 --- /dev/null +++ b/rde_schema/property_bank/license.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/license", + "title": "License", + "description": "A license governing the data's use.", + "type": "object", + "controlledVocab": "licenses", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Creative Commons Attribution 4.0 International", + "Apache License 1.0" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "CC-BY-NC-4.0", + "Apache-1.0" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/licenses/terms/CC-BY-4.0", + "/api/v1/vocab-terms/licenses/terms/Apache-1.0" + ] + } + }, + "required": ["label", "code", "uri"], + "examples": [ + { + "label": "Creative Commons Attribution 4.0 International", + "code": "CC-BY-NC-4.0", + "uri": "/api/v1/vocab-terms/licenses/terms/CC-BY-4.0" + }, + { + "label": "Apache License 1.0", + "code": "Apache-1.0", + "uri": "/api/v1/vocab-terms/licenses/terms/Apache-1.0" + } + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/manuscript_number.json b/rde_schema/property_bank/manuscript_number.json new file mode 100644 index 0000000..2e70831 --- /dev/null +++ b/rde_schema/property_bank/manuscript_number.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/manuscript_number", + "title": "Manuscript Number", + "description": "A unique identifier that associates the data collection with a manuscript submitted to a journal.", + "type": "string", + "examples": ["ECIN-Mar-2025-0078.R2", "AER-2019-0000"] +} \ No newline at end of file diff --git a/rde_schema/property_bank/mesh_subject_terms.json b/rde_schema/property_bank/mesh_subject_terms.json new file mode 100644 index 0000000..600a9f6 --- /dev/null +++ b/rde_schema/property_bank/mesh_subject_terms.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/mesh_subject_terms", + "title": "Medical Subject Headings (MeSH) Terms", + "description": "Biomedical and health-related terms from the National Library of Medicine that describe the data collection's topics.", + "usageNotes": "This controlled vocabulary was taken from the National Library of Medicine's Medical Subject Headings (MeSH). Source: [https://www.ncbi.nlm.nih.gov/mesh/](https://www.ncbi.nlm.nih.gov/mesh/)", + "type": "array", + "controlledVocab": "mesh", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the subject term.", + "type": "string", + "examples": ["Anxiety", "Diabetes Mellitus"] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the subject term.", + "type": "string", + "examples": ["D001007", "T011730"] + }, + "uri": { + "title": "URI", + "description": "The URI for the subject term as maintained in MeSH.", + "type": "string", + "examples": [ + "http://id.nlm.nih.gov/mesh/D001007", + "http://id.nlm.nih.gov/mesh/T011730" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Anxiety", + "code": "D001007", + "uri": "http://id.nlm.nih.gov/mesh/D001007" + }, + { + "label": "Diabetes Mellitus", + "code": "T011730", + "uri": "http://id.nlm.nih.gov/mesh/T011730" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/nationally_representative_sample.json b/rde_schema/property_bank/nationally_representative_sample.json new file mode 100644 index 0000000..cc87ce1 --- /dev/null +++ b/rde_schema/property_bank/nationally_representative_sample.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/nationally_representative_sample", + "title": "Nationally Representative Sample", + "description": "Indicates whether the data collection uses a sampling design intended to represent the demographics, behaviors, and/or characteristics of the entire nation. This typically involves probability-based methods that allow generalization. It does not include convenience samples that appear similar to the nation by chance.", + "type": "string", + "examples": ["Yes", "No"] +} \ No newline at end of file diff --git a/rde_schema/property_bank/notes.json b/rde_schema/property_bank/notes.json new file mode 100644 index 0000000..c915cb3 --- /dev/null +++ b/rde_schema/property_bank/notes.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/notes", + "title": "Notes", + "description": "Important details about the data collection (like unique authoring, discrepancies, or processing information) that can't be recorded in other metadata elements.", + "usageNotes": "Notes should include any information that does not fit anywhere else in the metadata, such as: information about unique aspects of the way the data was processed, discrepancies between the metadata and documentation files, information about the research team, or series-specific notes.", + "type": "array", + "items": { "type": "string" }, + "examples": [ + [ + "Information on the Index of Consumer Sentiment, the Index of Current Economic Conditions, and the Index of Consumer Expectations and how they were created can be found in the P.I. Codebook", + "Dataset 1 should be attributed to Jane Doe while datasets 2-6 should be attributed to John Doe" + ], + ["Additional information on the Survey of Consumers can be found by visiting the Survey of Consumers Website"] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/organization.json b/rde_schema/property_bank/organization.json new file mode 100644 index 0000000..e376e3a --- /dev/null +++ b/rde_schema/property_bank/organization.json @@ -0,0 +1,48 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/organization", + "title": "Organization", + "description": "An organization associated with an ICPSR data collection or service.", + "type": "object", + "controlledVocab": "organizations", + "properties": { + "name": { + "title": "Organization Name", + "description": "The organization's name.", + "type": "string", + "examples": [ + "Federal Reserve Bank of St. Louis", + "University of Michigan" + ] + }, + "ror": { + "title": "ROR Identifier", + "description": "The organization's Research Organization Registry (ROR) identifier.", + "type": "string", + "format": "uri", + "examples": [ "https://ror.org/02q7mkh03" ] + }, + "email": { + "title": "Email Address", + "description": "The organization's email address.", + "type": "string", + "format": "email", + "examples": ["info@example.com"] + } + }, + "required": ["name"], + "examples": [ + { + "name": "Urban Institute", + "ror": "https://ror.org/017pz3h73", + "email": "info@urban.institute" + }, + { + "name": "Bureau of Justice Statistics", + "ror": "https://ror.org/0006s4z66" + }, + { + "name": "Internal Revenue Service" + } + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/person.json b/rde_schema/property_bank/person.json new file mode 100644 index 0000000..155abf2 --- /dev/null +++ b/rde_schema/property_bank/person.json @@ -0,0 +1,103 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/person", + "title": "Person", + "description": "A person associated with an ICPSR data collection or service.", + "type": "object", + "properties": { + "name": { + "title": "Personal Name", + "description": "The person's name.", + "type": "object", + "properties": { + "given": { + "title": "Given Name (First Name)", + "description": "The person's first (given) name, which may include a middle name or initial.", + "type": "string", + "mapsTo": ["foaf:givenName"], + "examples": ["Miner P.", "Robert J.", "Claudia"] + }, + "family": { + "title": "Family Name (Last Name)", + "description": "The person's last (family) name, which may include a suffix (e.g., Jr., Sr., IV).", + "type": "string", + "mapsTo": ["foaf:familyName"], + "examples": ["Marchbanks III", "Shiller", "Goldin"] + } + }, + "required": ["given", "family"], + "examples": [ + { + "given": "Susan B.", + "family": "Anthony" + }, + { + "given": "John", + "family": "Doe IV" + } + ] + }, + "orcid": { + "title": "ORCID Identifier", + "description": "The person's Open Researcher and Contributor ID (ORCID).", + "type": "string", + "format": "uri", + "examples": [ "https://orcid.org/0009-0006-2316-6486", "https://orcid.org/0000-0003-3842-1604" ] + }, + "affiliations": { + "title": "Affiliation(s)", + "description": "The person's affiliated organization(s).", + "type": "array", + "items": { + "$ref": "https://archive.icpsr.umich.edu/schema/property_banks/organization/version/1", + "title": "Organization", + "description": "Name and other details about the principal investigator’s affiliation." + } + }, + "email": { + "title": "Email Address", + "description": "The person's email address.", + "type": "string", + "format": "email", + "examples": ["j.doe@example.com"] + } + }, + "required": ["name"], + "examples": [ + { + "name": { + "given": "Robert J.", + "family": "Shiller" + }, + "orcid": "https://orcid.org/0009-0006-2316-6486", + "affiliations": [ + { + "name": "Yale University", + "ror": "https://ror.org/03v76x132" + }, + { + "name": "MacroMarkets" + } + ] + }, + { + "name": { + "given": "Claudia", + "family": "Goldin" + }, + "orcid": "https://orcid.org/0000-0003-3842-1604", + "affiliations": [ + { + "name": "Harvard University", + "ror": "https://ror.org/03vek6s52" + } + ] + }, + { + "name": { + "given": "Miner P.", + "family": "Marchbanks III" + } + } + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/preregistration.json b/rde_schema/property_bank/preregistration.json new file mode 100644 index 0000000..c122288 --- /dev/null +++ b/rde_schema/property_bank/preregistration.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/preregistration", + "title": "Preregistration", + "description": "A link to a research plan for the data collection (preferably a persistent identifier such as a DOI).", + "type": "string", + "format": "uri", + "examples": [ + "https://doi.org/10.17605/OSF.IO/67DUT", "https://doi.org/10.1257/rct.15789-1.0" + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/principal_investigators.json b/rde_schema/property_bank/principal_investigators.json new file mode 100644 index 0000000..f776ef7 --- /dev/null +++ b/rde_schema/property_bank/principal_investigators.json @@ -0,0 +1,101 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/principal_investigators", + "title": "Principal Investigators", + "description": "The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization.", + "usageNotes": "List individuals and organizations that are chiefly responsible for the study across its entire life cycle or made significant intellectual contributions to the research.", + "type": "array", + "items": { + "type": "object", + "properties": { + "person": { + "$ref": "https://archive.icpsr.umich.edu/schema/property_banks/person/version/1", + "title": "Person", + "description": "Name and other details about the principal investigator, if it is an individual person.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/principal_investigators_person#/usageNotes" } + }, + "organization": { + "$ref": "https://archive.icpsr.umich.edu/schema/property_banks/organization/version/1", + "title": "Organization", + "description": "Name and other details about the principal investigator, if it is an organization.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/principal_investigators_organization#/usageNotes" } + }, + "order": { + "title": "Order", + "description": "The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI.", + "type": "integer", + "examples": [0,1,2] + } + }, + "allOf": [ + { + "oneOf": [ + { "required": ["person"] }, + { "required": ["organization"] } + ] + }, + { + "required": ["order"] + } + ] + }, + "minItems": 1, + "examples": [ + [ + { + "person": { + "name": { + "given": "Miner P.", + "family": "Marchbanks III" + } + }, + "order": 0 + } + ], + [ + { + "person": { + "name": { + "given": "Robert J.", + "family": "Shiller" + }, + "orcid": "https://orcid.org/0009-0006-2316-6486", + "affiliations": [ + { + "name": "Yale University", + "ror": "https://ror.org/03v76x132" + }, + { + "name": "MacroMarkets" + } + ] + }, + "order": 0 + }, + { + "person": { + "name": { + "given": "Claudia", + "family": "Goldin" + }, + "orcid": "https://orcid.org/0000-0003-3842-1604", + "affiliations": [ + { + "name": "Harvard University", + "ror": "https://ror.org/03vek6s52" + } + ] + }, + "order": 1 + }, + { + "organization": + { + "name": "Bureau of Justice Statistics", + "ror": "https://ror.org/0006s4z66" + }, + "order": 2 + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/response_rates.json b/rde_schema/property_bank/response_rates.json new file mode 100644 index 0000000..f421dae --- /dev/null +++ b/rde_schema/property_bank/response_rates.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/response_rates", + "title": "Response Rates", + "description": "The percentage of respondents in the sample who participated in the data collection.", + "type": "string", + "usageNotes": "This field is only applicable if the data were collected with a survey instrument and the response rates are provided.", + "examples": [ + "The overall response rate for this survey was 20.22%; 72.6% for existing panelists and 10.4% for new panelists, using AAPOR Response Rate 1.", + "Of the 1,843 Midlife in the United States (MIDUS) respondents that researchers attempted to contact, 1,483 agreed to participate (8 percent refused participation and 11 percent either moved or were difficult to contact), yielding a response rate of approximately 81 percent." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/sampling_note.json b/rde_schema/property_bank/sampling_note.json new file mode 100644 index 0000000..ae78885 --- /dev/null +++ b/rde_schema/property_bank/sampling_note.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/sampling_note", + "title": "Sampling Note", + "description": "Supplemental information about the sampling process that does not fit neatly into the Sampling Procedure field.", + "type": "string", + "usageNotes": "A detailed discussion of such things as sampling error or other limitations of the sampling methodology is not required here.", + "examples": [ + "National sample of telephone numbers from cell (RDD) sampling frame.", + "The probability sample selected to represent the universe consists of approximately 71,000 households." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/sampling_procedures.json b/rde_schema/property_bank/sampling_procedures.json new file mode 100644 index 0000000..c6065c5 --- /dev/null +++ b/rde_schema/property_bank/sampling_procedures.json @@ -0,0 +1,69 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/sampling_procedures", + "title": "Sampling Procedures", + "description": "The type(s) of sample and sample design used to select survey respondents to represent the population.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/sampling_procedures#/usageNotes" }, + "controlledVocab": "samplingProcedures", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Probability: Systematic random", + "Theoretical Sampling", + "Total universe/Complete enumeration" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "Probability.SystematicRandom", + "TheoreticalSampling", + "TotalUniverseCompleteEnumeration" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/samplingProcedures/terms/Probability.SystematicRandom", + "/api/v1/vocab-terms/samplingProcedures/terms/TheoreticalSampling", + "/api/v1/vocab-terms/samplingProcedures/terms/TotalUniverseCompleteEnumeration" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "items": { + "type": "string" + }, + "examples": [ + [ + { + "label": "Probability: Systematic random", + "code": "Probability.SystematicRandom", + "uri": "/api/v1/vocab-terms/samplingProcedures/terms/Probability.SystematicRandom" + }, + { + "label": "Theoretical Sampling", + "code": "TheoreticalSampling", + "uri": "/api/v1/vocab-terms/samplingProcedures/terms/TheoreticalSampling" + } + ], + [ + { + "label": "Total universe/Complete enumeration", + "code": "TotalUniverseCompleteEnumeration", + "uri": "/api/v1/vocab-terms/samplingProcedures/terms/TotalUniverseCompleteEnumeration" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/scales.json b/rde_schema/property_bank/scales.json new file mode 100644 index 0000000..9032990 --- /dev/null +++ b/rde_schema/property_bank/scales.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/scales", + "title": "Scales", + "description": "Any commonly known scales, measures, or inventories used in the data collection.", + "type": "string", + "usageNotes": "Include common scales that can be readily identified from the data, documentation, or other related materials. Examples of common scales include the Minnesota Multiphasic Personality Inventory (MMPI) and the Consumer Price Index (CPI). ICPSR curators are not expected to infer or research scales that are not explicitly indicated. The scales can be cited either as a list or described in full sentences and include DOIs or URLs whenever possible. If the questionnaire used has a finite list of responses (e.g., 'Always, Sometimes, Rarely, Never' or 'Strongly Agree, Agree, Disagree, Strongly Disagree'), it is acceptable for this element to note 'A Likert-type scale was used,' or 'Several Likert-type scales were used.' However, it is not required to note Likert-type scales in situations where only such scales were used, given their ubiquity.", + "examples": + [ + [ + "The baseline data collection included one scale - the CES-D index for maternal depression [Cole, J. C., Rabin, A. S., Smith, T. L., and Kaufman, A. S. (2004). Development and validation of a Rasch-derived CES-D short form. Psychological assessment, 16(4), 360. https://doi.org/10.1037/1040-3590.16.4.360]. All scales used for outcomes at ages 1 through 3 are listed in Appendix Tables 1 and 2 in the User Guide. Please refer to the User Guide and P.I. Codebook, available under the 'Data and Documentation' tab, for details." + ], + [ + "Squires, J., Bricker, D. D., and Twombly, E. (2009). Ages and stages questionnaires. Baltimore, MD: Paul H. Brookes.", + "Briggs-Gowan, M. J., Carter, A. S., Irwin, J. R., Wachtel, K., and Cicchetti, D. V. (2004). The Brief Infant-Toddler Social and Emotional Assessment: screening for social-emotional problems and delays in competence. Journal of pediatric psychology, 29(2), 143-155. https://doi.org/10.1093/jpepsy/jsh017", + "Yu, L., Buysse, D. J., Germain, A., Moul, D. E., Stover, A., Dodds, N. E., ... and Pilkonis, P. A. (2012). Development of short forms from the PROMIS sleep disturbance and sleep-related impairment item banks. Behavioral sleep medicine, 10(1), 6-24. https://doi.org/10.1080/15402002.2012.636266" + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/smallest_geographic_unit.json b/rde_schema/property_bank/smallest_geographic_unit.json new file mode 100644 index 0000000..6be28ae --- /dev/null +++ b/rde_schema/property_bank/smallest_geographic_unit.json @@ -0,0 +1,58 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/smallest_geographic_unit", + "title": "Smallest Geographic Unit", + "description": "The smallest geographic unit (e.g., state or census tract) used in the dataset.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/smallest_geographic_unit#/usageNotes" }, + "controlledVocab": "smallestGeographicUnits", + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Basic Geographic Units", + "Postal Code/Zip Code", + "State/Province" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "BasicUnits", + "PostalCodeZipCode", + "StateProvince" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/smallestGeographicUnits/terms/BasicUnits", + "/api/v1/vocab-terms/smallestGeographicUnits/terms/PostalCodeZipCode", + "/api/v1/vocab-terms/smallestGeographicUnits/terms/StateProvince" + ] + } + }, + "examples": [ + { + "label": "Basic Geographic Units", + "code": "BasicUnits", + "uri": "/api/v1/vocab-terms/smallestGeographicUnits/terms/BasicUnits" + }, + { + "label": "Postal Code/Zip Code", + "code": "PostalCodeZipCode", + "uri": "/api/v1/vocab-terms/smallestGeographicUnits/terms/PostalCodeZipCode" + }, + { + "label": "State/Province", + "code": "StateProvince", + "uri": "/api/v1/vocab-terms/smallestGeographicUnits/terms/StateProvince" + } + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/software_applications.json b/rde_schema/property_bank/software_applications.json new file mode 100644 index 0000000..7998fbe --- /dev/null +++ b/rde_schema/property_bank/software_applications.json @@ -0,0 +1,179 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/core/software_applications", + "title": "Software Applications", + "description": "Software used by the principal investigator(s) to collect or analyze data, required to understand how the data were obtained or to reproduce results.", + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "title": "Software Name", + "description": "The name of the software application.", + "type": "string", + "examples": [ + "JHOVE", + "ffmpeg", + "json-schema-for-humans" + ] + }, + "software_version": { + "title": "Software Version", + "description": "The version of the application.", + "type": "string", + "examples": [ + "1", + "2.0.4", + "Auto-Build 2023-01-15 12:36" + ] + }, + "description": { + "title": "Software Description", + "description": "Short description or overview of the application and its intended purpose", + "type": "string", + "examples": [ + "JHOVE, the JSTOR/Harvard Object Validation Environment, is an extensible software framework for performing format identification, validation, and characterization of digital objects.", + "ffmpeg is a very fast video and audio converter that can also grab from a live audio/video source. It can also convert between arbitrary sample rates and resize video on the fly with a high quality polyphase filter." + ] + }, + "programming_languages": { + "title": "Programming Languages", + "description": "The programming language(s) used in the development of the application", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "python" + ], + [ + "shell", + "r" + ], + [ + "other" + ] + ] + }, + "operating_systems": { + "title": "Operating Systems", + "description": "Computer operating systems supported by the application", + "type": "array", + "items": { + "type": "string" + }, + "examples": [ + [ + "windows" + ], + [ + "windows", + "mac", + "linux" + ], + [ + "other" + ] + ] + }, + "memory_requirements": { + "title": "Memory Requirements", + "description": "Minimum memory (e.g., RAM) requirements to operate the application", + "type": "string", + "examples": [ + "4 GB", + "1GB of RAM (2GB for a 64-bit version)", + "4 GB of GPU memory for HD and some 4K media; 6 GB or more for 4K and higher" + ] + }, + "processor_requirements": { + "title": "Processor Requirements", + "description": "Processor architecture required to run the application", + "type": "string", + "examples": [ + "Intel i5/ i7/ Ryzen 7", + "Minimum 1 GHz; Recommended 2GHz or more", + "2.5–2.9 GHz or faster processor" + ] + }, + "software_requirements": { + "title": "Software Requirements", + "description": "Required components for the application, like runtime environments and shared libraries not included in the package but needed to run it.", + "type": "string", + "examples": [ + "Java runtime environment", + "Requires additional Python libraries: numpy, v1.11.2; scipy, v0.18.1, and pandas, v0.19.0", + "Compile with GNU auto tools" + ] + }, + "storage_requirements": { + "title": "Storage Requirements", + "description": "Amount of storage space required by the application", + "type": "string", + "examples": [ + "3.5 GB for new installations, 5 GB for upgrades (including temporary files required during installation)", + "15 GB of free disk space", + "8 GB of available hard-disk space for installation; additional free space required during installation" + ] + }, + "device_requirements": { + "title": "Device Requirements", + "description": "Device required to run the application. Used in cases where a specific make/model is required to run the application", + "type": "string", + "examples": [] + }, + "license": { + "title": "License", + "description": "The license associated with the application, preferably expressed as a URL.", + "type": "string", + "examples": [ + "https://www.apache.org/licenses/LICENSE-2.0", + "https://opensource.org/licenses/LGPL-2.0" + ] + }, + "download_url": { + "title": "Download URL", + "description": "A direct link to a downloadable software artifact (e.g., executable, package, archive, or single script file) that retrieves the application itself, without additional navigation or instructions.", + "type": "string", + "format": "uri", + "examples": [ + "https://github.com/richardlehane/siegfried/archive/refs/heads/main.zip", + "https://cdn.nationalarchives.gov.uk/documents/droid-binary-6.5.2-bin-win32-with-jre.zip" + ] + }, + "install_url": { + "title": "Installation URL", + "description": "A link to a repository or project landing page where users can obtain resources and instructions to install the application (as opposed to directly downloading a single file).", + "type": "string", + "format": "uri", + "examples": [ + "https://github.com/richardlehane/siegfried", + "https://www.nationalarchives.gov.uk/information-management/manage-information/preserving-digital-records/droid/" + ] + } + }, + "required": ["name"] + }, + "examples": [ + [ + { + "name": "siegfried", + "software_version": "1.11.1", + "description": "Siegfried is a signature-based file format identification tool, implementing the National Archives UK's PRONOM file format signatures; freedesktop.org's MIME-info file format signatures; the Library of Congress's FDD file format signatures (beta); and Wikidata (beta).", + "programming_languages": [ + "go", + "javascript", + "other" + ], + "operating_systems": [ + "mac", + "linux", + "windows" + ], + "license": "https://www.apache.org/licenses/LICENSE-2.0", + "download_url": "https://github.com/richardlehane/siegfried/archive/refs/heads/main.zip" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/study_design.json b/rde_schema/property_bank/study_design.json new file mode 100644 index 0000000..57a5c91 --- /dev/null +++ b/rde_schema/property_bank/study_design.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/study_design", + "title": "Study Design", + "description": "The procedures used to contact participants and gather data.", + "type": "string", + "usageNotes": "The Study Design provides more detailed information than the Summary, including how surveys were prepared and administered, how interviews were conducted, or how the data were obtained and compiled, as well as information about deadlines and follow-ups to respondents.", + "examples": + [ + "Data on organizational culture in each of the 12 courts (Part 1) were obtained by administering the Court Culture Assessment Instrument (CCAI) to all judges with a felony criminal court docket and to all senior court administrators. A total of 224 respondents completed the questionnaire. The CCAI was used to assess five key dimensions of current court culture orientation: (1) dominant case management style, (2) judicial and court staff relations, (3) change management, (4) courthouse leadership, and (5) internal organization. The determination of what culture judges and court administrators desired to establish in the near future was also obtained through the application of the same instrument (CACI) as practitioners were asked to indicate the type of culture in each work area (or content dimension) they would like to see in their court in the next five years." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/study_number.json b/rde_schema/property_bank/study_number.json new file mode 100644 index 0000000..29e97d6 --- /dev/null +++ b/rde_schema/property_bank/study_number.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/study_number", + "title": "Study Number", + "description": "A unique, numerical value used by ICPSR to identify and track data collections.", + "type": "integer", + "usageNotes": "The study number is automatically generated by ICPSR and is unique. Current study numbers are five or six digits, though four digit numbers were once standard and are still acceptable.", + "examples": [2760, 3025, 38672] +} diff --git a/rde_schema/property_bank/summary.json b/rde_schema/property_bank/summary.json new file mode 100644 index 0000000..410f4d0 --- /dev/null +++ b/rde_schema/property_bank/summary.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/summary", + "title": "Summary", + "description": "A description of the data collection that helps users understand its purpose, substance, and key topics.", + "type": "string", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/summary#/usageNotes" }, + "examples": [ + "In 2014, Chicago Public Schools, looking to reduce the possibility of gun violence among school-aged youth, applied for a grant through the National Institute of Justice. CPS was awarded the Comprehensive School Safety Initiative grant and use said grant to establish the 'Connect and Redirect to Respect' program. This program used student social media data to identify and intervene with students thought to be at higher risk for committing violence. At-risk behaviors included brandishing a weapon, instigating conflict online, signaling gang involvement, and threats towards others. Identified at-risk students would be contacted by a member of the CPS Network Safety Team or the Chicago Police Department's Gang School Safety Team, depending on the risk level of the behavior. To evaluate the efficacy of CRR, the University of Chicago Crime Lab compared outcomes for students enrolled in schools that received the program to outcomes for students enrolled in comparison schools, which did not receive the program. 32 schools were selected for the study, with a total of 44,503 students. Demographic variables included age, race, sex, and ethnicity. Misconduct and academic variables included arrest history, in-school suspensions, out-of-school suspensions, GPA, and attendance days.", + "The Health and Relationship Project is a study of both spouses in same-sex and different-sex marriages who were legally married and aged 35 to 65 at the time of data collection (2015). There are two parts of this study: a baseline questionnaire and a daily diary questionnaire completed for 10 consecutive days; both components were completed online and spouses were asked to complete the surveys separately. The baseline questionnaire asks participants about a number of topics related to marriage and health, including stress, health status and health behaviors, relationship quality, and how they have approached health problems in the past. The diary questionnaire asks participants a number of questions about the past 24 hours, including daily stress experiences, social interactions, and health behaviors." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/time_methods.json b/rde_schema/property_bank/time_methods.json new file mode 100644 index 0000000..ba665b0 --- /dev/null +++ b/rde_schema/property_bank/time_methods.json @@ -0,0 +1,66 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/time_methods", + "title": "Time Methods", + "description": "The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends.", + "usageNotes": "This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV TimeMethod [https://rdf-vocabulary.ddialliance.org/ddi-cv/TimeMethod/1.2.3/TimeMethod.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/TimeMethod/1.2.3/TimeMethod.html).", + "controlledVocab": "timeMethods", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Cross-section", + "Longitudinal: Panel", + "Time series" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "CrossSection", + "Longitudinal.Panel", + "TimeSeries" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/timeMethods/terms/CrossSection", + "/api/v1/vocab-terms/timeMethods/terms/Longitudinal.Panel", + "/api/v1/vocab-terms/timeMethods/terms/TimeSeries" + ] + } + }, + "required": [ "label", "code", "uri" ] + }, + "examples": [ + [ + { + "label": "Cross-section", + "code": "CrossSection", + "uri": "/api/v1/vocab-terms/timeMethods/terms/CrossSection" + }, + { + "label": "Longitudinal: Panel", + "code": "Longitudinal.Panel", + "uri": "/api/v1/vocab-terms/timeMethods/terms/Longitudinal.Panel" + } + ], + [ + { + "label": "Time series", + "code": "TimeSeries", + "uri": "/api/v1/vocab-terms/timeMethods/terms/TimeSeries" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/time_periods.json b/rde_schema/property_bank/time_periods.json new file mode 100644 index 0000000..3b5d8e6 --- /dev/null +++ b/rde_schema/property_bank/time_periods.json @@ -0,0 +1,52 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/time_periods", + "title": "Time Periods", + "description": "The time period(s) to which the data refer, regardless of when the data were collected.", + "type": "array", + "items": { + "type": "object", + "properties": { + "start_date": { + "title": "Start Date", + "description": "The start date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions.", + "type": "string", + "examples": ["2000", "2019-10", "2021-03-01"] + }, + "end_date": { + "title": "End Date", + "description": "The end date for the time period the data refer to, formatted as YYYY, YYYY-MM, or YYYY-MM-DD, with no spaces in date expressions.", + "type": "string", + "examples": ["2000", "2019-10", "2021-03-01"] + }, + "time_frame": { + "title": "Time Frame", + "description": "An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present.", + "type": "string", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/time_periods_time_frame#/usageNotes" }, + "examples": [ "Fall 2001", "Winter Semester 2019"] + } + }, + "required": ["start_date", "end_date"] + }, + "minItems": 1, + "examples": [ + [ + { + "start_date": "2018", + "end_date": "2018", + "time_frame": "Summer and Fall 2018" + }, + { + "start_date": "2020-10", + "end_date": "2020-10" + } + ], + [ + { + "start_date": "2003-01-01", + "end_date": "2003-12-31" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/title.json b/rde_schema/property_bank/title.json new file mode 100644 index 0000000..3850f5d --- /dev/null +++ b/rde_schema/property_bank/title.json @@ -0,0 +1,15 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/title", + "title": "Title", + "description": "The official title that describes what the data collection is about, its geographic scope, and the time period it covered.", + "usageNotes": { "$ref": "https://schemas.icpsr.umich.edu/notes/title#/usageNotes" }, + "type": "string", + "examples": [ + "Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project, Kansas City, Missouri, 2014-2017", + "Health and Relationships Project, United States, 2014-2015", + "Targeted Interventions to Prevent Chronic Low Back Pain in High Risk Patients: A Multi-Site Pragmatic Randomized Controlled Trial (TARGET Trial), 4 U.S. cities, 2016-2019", + "Aid Like A Paycheck (ALAP), Texas and California, 2014-2017", + "COVID-19 Disruptions Disproportionately Affect Female Academics, Global, 2020" + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/units_of_analysis.json b/rde_schema/property_bank/units_of_analysis.json new file mode 100644 index 0000000..51498b9 --- /dev/null +++ b/rde_schema/property_bank/units_of_analysis.json @@ -0,0 +1,66 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/units_of_analysis", + "title": "Units of Analysis", + "description": "The object(s) of analysis for the data collection, such as an organization, individual, or household.", + "usageNotes": "This controlled vocabulary was taken from the DDI Alliance. Source: DDI Alliance CV AnalysisUnit [https://rdf-vocabulary.ddialliance.org/ddi-cv/AnalysisUnit/2.1.3/AnalysisUnit.html](https://rdf-vocabulary.ddialliance.org/ddi-cv/AnalysisUnit/2.1.3/AnalysisUnit.html).", + "controlledVocab": "analysisUnits", + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "title": "Label", + "description": "A human-readable form of the term.", + "type": "string", + "examples": [ + "Organization/Institution", + "Individual", + "Household" + ] + }, + "code": { + "title": "Code", + "description": "A machine-readable/-actionable form of the term.", + "type": "string", + "examples": [ + "OrganizationOrInstitution", + "Individual", + "Household" + ] + }, + "uri": { + "title": "URI", + "description": "The URI for the term.", + "type": "string", + "examples": [ + "/api/v1/vocab-terms/analysisUnits/OrganizationOrInstitution", + "/api/v1/vocab-terms/analysisUnits/Individual", + "/api/v1/vocab-terms/analysisUnits/Household" + ] + } + }, + "required": ["label", "code", "uri"] + }, + "examples": [ + [ + { + "label": "Organization/Institution", + "code": "OrganizationOrInstitution", + "uri": "/api/v1/vocab-terms/analysisUnits/OrganizationOrInstitution" + }, + { + "label": "Individual", + "code": "Individual", + "uri": "/api/v1/vocab-terms/analysisUnits/Individual" + } + ], + [ + { + "label": "Household", + "code": "Household", + "uri": "/api/v1/vocab-terms/analysisUnits/Household" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/universe.json b/rde_schema/property_bank/universe.json new file mode 100644 index 0000000..a044100 --- /dev/null +++ b/rde_schema/property_bank/universe.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/universe", + "title": "Universe", + "description": "The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer.", + "type": "string", + "usageNotes": "Age, nationality, and residence commonly help to delineate a given universe, but any of a number of factors may be involved, such as sex, race, income, veteran status, criminal convictions, etc. The Universe may consist of elements other than persons, such as housing units, court cases, deaths, countries, etc. It should be possible to tell from the description of the universe whether a given individual or element (hypothetical or real) is a member of the population under study. Typically, the Universe statement is about one sentence or shorter, and reflects the entire possible population a data collection sought to study.", + "examples": + [ + "All households in the United States with phones.", + "Part 1: Thirty cities in Massachusetts during 1980-1986. Parts 2-4: All residents in Massachusetts during 1986.", + "Individuals self-identified as transgender, trans, genderqueer, non-binary, or other identities on the transgender identity spectrum aged 18 and older residing in the fifty U.S. states, the District of Columbia, American Samoa, Guam, Puerto Rico, and U.S. military bases overseas.", + "Jihadists from the United States and Canada, along with Incels from Germany, Canada, the United States, and United Kingdom.", + "All publicly funded medical examiner and coroner offices.", + "Uncertified ballots for the 2000 United States presidential election in Florida." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/variable_description.json b/rde_schema/property_bank/variable_description.json new file mode 100644 index 0000000..434e610 --- /dev/null +++ b/rde_schema/property_bank/variable_description.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/variable_description", + "title": "Variable Description", + "description": "Significant variables (particularly demographic variables) in the data files.", + "type": "string", + "usageNotes": "The Variable Description provides more detailed information than the Summary, including a review of variables that are important for users to know about. The codebook, setup files, and variable groups are appropriate sources of information for Variable Description.", + "examples": [ + "The data includes variables about participants' and their parents' moods, interviewer observations, families' activities, families' health history, participants' school records, and parents' substance use. Demographic variables include race, religion, annual household income, and the participants' parents' employment statuses.", + "The LGBTQ Hate Crimes Interviews dataset contains more in-depth information, including victim demographic information, substance abuse history, information on whether the victim is open about their LGBTQ identification, the victim's job status, and information about how the victim reacted to the crime, such as whether or not they reported the crime to the police and their level of cooperation with the police and prosecution." + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/version_history.json b/rde_schema/property_bank/version_history.json new file mode 100644 index 0000000..608bda5 --- /dev/null +++ b/rde_schema/property_bank/version_history.json @@ -0,0 +1,68 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/version_history", + "title": "Version History", + "description": "A record of how the data collection has changed over time.", + "type": "array", + "items": { + "type": "object", + "properties": { + "version_number": { + "title": "Version Number", + "description": "A version number for a study.", + "type": "string", + "pattern": "^[vV]\\d+(.\\d+)?(.\\d+)?$", + "usageNotes": "Every ICPSR data collection is assigned version 1.0 when it is first published. When the data collection is updated, a new version number is assigned. For substantive changes to the data collection, including changes to data files, title, or principal investigators, a new major version is created, the version number increases by 1 (for example, from 1.0 to 2.0), and a new version-specific digital object identifier (DOI) is created. For all other changes, a new minor version is created, the version number increases by 0.1 (for example, from 2.0 to 2.1), and the DOI does not change.", + "examples": [ + "V1", + "V2.1", + "V3.2" + ] + }, + "version_date": { + "title": "Version Date", + "description": "The date on which a given version of a data collection was released.", + "usageNotes": "ICPSR automatically generates this date for data collection additions and updates.", + "type": "string", + "format": "date", + "examples": ["2020-07-20", "2022-01-31"] + }, + "version_note": { + "title": "Version Note", + "description": "Provenance information about a given version of the data collection.", + "type": "string", + "examples": [ + "File CB3025.ALL.PDF was removed from any previous datasets and flagged as a study-level file, so that it will accompany all downloads.", + "The data producer provided additional data files.", + "The codebook descriptions of variables TANSUP, EMOSUP, and SOCSUP were corrected." + ] + } + } + }, + "examples": [ + [ + { + "version_number": "V2.1", + "version_date": "2025-10-03", + "version_note": "Updated study summary." + }, + { + "version_number": "V2", + "version_date": "2023-08-12", + "version_note": "The data producer provided additional data files." + }, + { + "version_number": "V1", + "version_date": "2021-03-01", + "version_note": "Initial release" + } + ], + [ + { + "version_number": "V1", + "version_date": "2024-06-28", + "version_note": "Initial release" + } + ] + ] +} \ No newline at end of file diff --git a/rde_schema/property_bank/weight.json b/rde_schema/property_bank/weight.json new file mode 100644 index 0000000..c300d56 --- /dev/null +++ b/rde_schema/property_bank/weight.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "$id": "https://archive.icpsr.umich.edu/schema/property_banks/weight", + "title": "Weights", + "description": "The weight variables and the criteria for using them in data analysis, or other information about how the data are weighted if no weight variables are present.", + "type": "string", + "usageNotes": "Weight includes any information about weighting variables in the data, as well as any other weight information provided by the Principal Investigator. If a weighting formula or coefficient was developed, provide this formula, define its elements, and indicate how the formula is applied to the data. It is acceptable to summarize additional documentation and refer users to those resources for more information.", + "examples": [ + "Both the TransPop and Cisgender datasets have the same variable named WEIGHT as the weighting variable. The combination datasets have a set of three weight variables (WEIGHT_TRANSPOP, WEIGHT_CISGENDER, WEIGHT_CISGENDER_TRANSPOP)", + "A weight variable with two implied decimal places has been included and must be used in any analysis." + ] +} \ No newline at end of file diff --git a/rde_schema/vocab_preset/data/adaAccessibility.json b/rde_schema/vocab_preset/data/adaAccessibility.json new file mode 100644 index 0000000..5df8998 --- /dev/null +++ b/rde_schema/vocab_preset/data/adaAccessibility.json @@ -0,0 +1,14 @@ +[ + { + "label": "ADA Accessible", + "code": "ada.accessible", + "description": "The item is ADA accessible, conforming to WCAG 2.1 AA standards.", + "type": "TreeVocabTermDTO" + }, + { + "label": "ADA Archival", + "code": "ada.archival", + "description": "The item is not ADA accessible, but qualifies for the ADA archival exception.", + "type": "TreeVocabTermDTO" + } +] \ No newline at end of file diff --git a/rde_schema/vocab_preset/data/contributorTypes.json b/rde_schema/vocab_preset/data/contributorTypes.json new file mode 100644 index 0000000..593f60d --- /dev/null +++ b/rde_schema/vocab_preset/data/contributorTypes.json @@ -0,0 +1,32 @@ +[ + { + "code": "DataCollector", + "label": "Data Collector", + "description": "The person/organization responsible for finding or gathering/collecting data under the guideance of the Principal Investigator (PI).", + "type": "TreeVocabTermDTO" + }, + { + "code": "DataCurator", + "label": "Data Curator", + "description": "The person/organization responsible for reviewing, enhancing, cleaning, and/or standardizing the data and associated metadata submitted to the repository.", + "type": "TreeVocabTermDTO" + }, + { + "code": "DataManager", + "label": "Data Manager", + "description": "The person/organization responsible for maintaining the finished data resource.", + "type": "TreeVocabTermDTO" + }, + { + "code": "ProjectManager", + "label": "Project Manager", + "description": "A person/organization officially designated as the manager of a project (which may consist of one or many project teams and sub-teams).", + "type": "TreeVocabTermDTO" + }, + { + "code": "Researcher", + "label": "Researcher", + "description": "A person/organization involved in analysing data or the results of an experiment or formal study. May indicate an intern or assistant who helped with research but was not listed as a Principal Investigator.", + "type": "TreeVocabTermDTO" + } +] \ No newline at end of file diff --git a/rde_schema/vocab_preset/data/oversamples.json b/rde_schema/vocab_preset/data/oversamples.json new file mode 100644 index 0000000..6ea83ca --- /dev/null +++ b/rde_schema/vocab_preset/data/oversamples.json @@ -0,0 +1,32 @@ +[ + { + "code": "Age", + "label": "Age", + "description": "Oversampling based on specific age groups (e.g., children, young adults, older adults).", + "type": "TreeVocabTermDTO" + }, + { + "code": "RaceEthnicity", + "label": "Race/Ethnicity", + "description": "Oversampling based on self-identified racial or ethnic backgrounds (e.g., Black/African American, Hispanic/Latino, Indigenous populations).", + "type": "TreeVocabTermDTO" + }, + { + "code": "SexualOrientationGenderIdentity", + "label": "Sexual Orientation/Gender Identity (SOGI)", + "description": "Oversampling based on self-reported sexual orientation (e.g., lesbian, gay, bisexual) or gender identity (e.g., transgender, non-binary).", + "type": "TreeVocabTermDTO" + }, + { + "code": "Sex", + "label": "Sex", + "description": "Oversampling based on sex assigned at birth (e.g., male, female).", + "type": "TreeVocabTermDTO" + }, + { + "code": "CitizenshipImmigrationStatus", + "label": "Citizenship/Immigration Status", + "description": "Oversampling based on citizenship, residency, or immigration classifications (e.g., naturalized citizens, undocumented immigrants, refugees).", + "type": "TreeVocabTermDTO" + } +] \ No newline at end of file diff --git a/rde_schema/vocab_preset/data/psidLicense.json b/rde_schema/vocab_preset/data/psidLicense.json new file mode 100644 index 0000000..a8497b8 --- /dev/null +++ b/rde_schema/vocab_preset/data/psidLicense.json @@ -0,0 +1,8 @@ +[ + { + "code": "psidLicense", + "label": "PSID License", + "description": "

You agree not to redistribute data or other materials without the written agreement of ICPSR, unless:

", + "type": "TreeVocabTermDTO" + } +] \ No newline at end of file diff --git a/rde_schema/vocab_preset/data/smallestGeographicUnits.json b/rde_schema/vocab_preset/data/smallestGeographicUnits.json new file mode 100644 index 0000000..e1f5f47 --- /dev/null +++ b/rde_schema/vocab_preset/data/smallestGeographicUnits.json @@ -0,0 +1,208 @@ +[ + { + "code": "BasicUnits", + "label": "Basic Geographic Units", + "description": "Basic geographic units for use with the Smallest Geographic Unit metadata property", + "type": "TreeVocabTermDTO" + }, + { + "code": "GeocodedLocation", + "label": "Geocoded Location", + "description": "A precise geographic point derived from an address, typically represented as coordinates or address strings.", + "type": "TreeVocabTermDTO", + "path": "BasicUnits" + + }, + { + "code": "Parcel", + "label": "Parcel", + "description": "A discrete use of land ownership, often defined in property records or tax assessments.", + "type": "TreeVocabTermDTO", + "path": "BasicUnits" + }, + { + "code": "GridCell", + "label": "Grid Cell", + "description": "A unit of spatial data that divides an area into rectangular, square intervals (e.g., 1km x 1km grid), typically used in mapping or environmental studies.", + "type": "TreeVocabTermDTO", + "path": "BasicUnits" + }, + { + "code": "LocalUnits", + "label": "Local Geographic Units", + "description": "Local geographic units for use with the Smallest Geographic Unit metadata property", + "type": "TreeVocabTermDTO" + }, + { + "code": "PostalCodeZipCode", + "label": "Postal Code/Zip Code", + "description": "A geographic area defined by postal delivery routes or regions, used for organizing mail delivery.", + "type": "TreeVocabTermDTO", + "path": "LocalUnits" + }, + { + "code": "NeighborhoodCommunityArea", + "label": "Neighborhood/Community Area", + "description": "An informally defined area within a city, usually based on local recognition rather than official administrative boundaries.", + "type": "TreeVocabTermDTO", + "path": "LocalUnits" + }, + { + "code": "CityMunicipality", + "label": "City/Municipality", + "description": "A local government jurisdiction that covers urban areas, which can range from large cities to small towns and villages.", + "type": "TreeVocabTermDTO", + "path": "LocalUnits" + }, + { + "code": "CountyDistrictParish", + "label": "County/District/Parish", + "description": "A geographic area that is part of a state or province (e.g., parishes in Louisiana, boroughs in Alaska).", + "type": "TreeVocabTermDTO", + "path": "LocalUnits" + }, + { + "code": "LargerUnits", + "label": "Larger Geographic Units", + "description": "Larger geographic units for use with the Smallest Geographic Unit metadata property", + "type": "TreeVocabTermDTO" + }, + { + "code": "StateProvince", + "label": "State/Province", + "description": "A major administrative division within a country. In the U.S., this includes the 50 states and the District of Columbia. Other countries, like Canada and Australia, have provinces or states (e.g., Ontario in Canada, New South Wales in Australia).", + "type": "TreeVocabTermDTO", + "path": "LargerUnits" + }, + { + "code": "Territory", + "label": "Territory", + "description": "A region under the jurisdiction of a national government, but not a fully self-governing state or province (e.g., Puerto Rico, Northwest Territories, Falkland Islands).", + "type": "TreeVocabTermDTO", + "path": "LargerUnits" + }, + { + "code": "Country", + "label": "Country", + "description": "A sovereign nation or territory that is recognized as an independent political entity, such as the United States, Canada, or France.", + "type": "TreeVocabTermDTO", + "path": "LargerUnits" + }, + { + "code": "CensusUnits", + "label": "Census Units", + "description": "Census units for use with the Smallest Geographic Unit metadata property", + "type": "TreeVocabTermDTO" + }, + { + "code": "CensusBlock", + "label": "Census Block", + "description": "The smallest geographic unit used in national censuses, often corresponding to a city block or small neighborhood.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "CensusBlockGroup", + "label": "Census Block Group", + "description": "A collection of adjacent census blocks—typically all blocks within part of a census tract.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "CensusTract", + "label": "Census Tract", + "description": "A small geographic unit used in national censuses, typically representing 2,500 to 8,000 people. Census tracts are designed to provide detailed statistical data for neighborhoods or communities.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "CensusDivision", + "label": "Census Division", + "description": "A larger geographic area used for statistical reporting, grouping states or provinces within a country. Census divisions are smaller than regions but larger than individual states or provinces.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "CensusRegion", + "label": "Census Region", + "description": "A broader grouping of census divisions used to organize and report data at a national level (e.g., Northeast, Midwest, South, West).", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "PublicUseMicrodataArea", + "label": "Public Use Microdata Area (PUMA)", + "description": "A geographic area with a population of 100,000 or more, used for the release of detailed public-use microdata from the U.S. Census.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "CoreBasedStatisticalArea", + "label": "Core-Based Statistical Area (CBSA)", + "description": "A term that includes both Metropolitan and Micropolitan Statistical Areas. These areas are based on urban centers and their surrounding communities as defined by the U.S. Office of Management and Budget (OMB).", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "MetropolitanStatisticalArea", + "label": "Metropolitan Statistical Area (MSA)", + "description": "A Core-Based Statistical Area (CBSA) that includes an urban core with a population of 50,000 or more.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "MicropolitanStatisticalArea", + "label": "Micropolitan Statistical Area", + "description": "A Core-Based Statistical Area (CBSA) that includes an urban core population of at least 10,000 but less than 50,000.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "ZIPCodeTabulationArea", + "label": "ZIP Code Tabulation Area (ZCTA)", + "description": "A geographic area created by the U.S. Census Bureau to approximate the boundaries of ZIP Codes for demographic analysis.", + "type": "TreeVocabTermDTO", + "path": "CensusUnits" + }, + { + "code": "ElectoralLegalCrossJurisdictionalEducationalDistricts", + "label": "Electoral, Legal, Cross-Jurisdictional, and Educational Districts", + "description": "Geographic units that represent electoral, legal, cross-jurisdictional, and educational districts for use with the Smallest Geographic Unit metadata property", + "type": "TreeVocabTermDTO" + }, + { + "code": "VotingDistrictPrecinct", + "label": "Voting District/Precinct", + "description": "A geographic area used for organizing elections, often serving as the smallest electoral units where voters cast their ballots.", + "type": "TreeVocabTermDTO", + "path": "ElectoralLegalCrossJurisdictionalEducationalDistricts" + }, + { + "code": "CongressionalDistrict", + "label": "Congressional District", + "description": "A geographic area used for electing representatives to federal or state legislative offices in the United States.", + "type": "TreeVocabTermDTO", + "path": "ElectoralLegalCrossJurisdictionalEducationalDistricts" + }, + { + "code": "FederalCourtDistrict", + "label": "Federal Court District", + "description": "A geographic area where a U.S. District Court has jurisdiction to hear and decide federal cases.", + "type": "TreeVocabTermDTO", + "path": "ElectoralLegalCrossJurisdictionalEducationalDistricts" + }, + { + "code": "SchoolDistrict", + "label": "School District", + "description": "The administrative boundary for local education systems, typically overseeing public schools from elementary through secondary levels.", + "type": "TreeVocabTermDTO", + "path": "ElectoralLegalCrossJurisdictionalEducationalDistricts" + }, + { + "code": "IndigenousTribalLands", + "label": "Indigenous/Tribal Lands", + "description": "An area legally recognized as an Indigenous or tribal nation, often with unique legal, cultural, or sovereignty status.", + "type": "TreeVocabTermDTO", + "path": "ElectoralLegalCrossJurisdictionalEducationalDistricts" + } +] \ No newline at end of file diff --git a/rde_schema/vocab_preset/definitions.json b/rde_schema/vocab_preset/definitions.json new file mode 100644 index 0000000..74876da --- /dev/null +++ b/rde_schema/vocab_preset/definitions.json @@ -0,0 +1,174 @@ +[ + { + "code": "classifications", + "label": "Classifications", + "description": "ICPSR Classification System", + "adapter": "icpsr_classification", + "termCodeType": "STRING" + }, + { + "code": "collectionModes", + "label": "Collection Modes", + "description": "DDI Collection Mode Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/ModeOfCollection", + "externalVersion": "5.0.0", + "termCodeType": "STRING", + "initParams": "ModeOfCollection" + }, + { + "code": "dataSourceTypes", + "label": "Data Source Types", + "description": "DDI Data Source Type Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/DataSourceType", + "externalVersion": "1.0.2", + "termCodeType": "STRING", + "initParams": "DataSourceType" + }, + { + "code": "generalDataFormats", + "label": "General Data Formats", + "description": "DDI General Data Format Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/GeneralDataFormat", + "externalVersion": "2.0.3", + "termCodeType": "STRING", + "initParams": "GeneralDataFormat" + }, + { + "code": "subjectTerms", + "label": "Subject Terms", + "description": "ICPSR Subject Terms Thesaurus", + "adapter": "icpsr_thesaurus", + "termCodeType": "STRING", + "initParams": "10001" + }, + { + "code": "jelClassifications", + "label": "JEL Classifications", + "description": "Journal of Economic Literature Classification System", + "adapter": "jel", + "termCodeType": "STRING" + }, + { + "code": "licenses", + "label": "Licenses", + "description": "SPDX License List", + "adapter": "licenses", + "externalURI": "https://spdx.org/licenses/", + "externalVersion": "", + "termCodeType": "STRING" + }, + { + "code": "mesh", + "label": "MESH", + "description": "NLM Medical Subject Headings", + "adapter": "mesh_proxy", + "externalURI": "https://id.nlm.nih.gov/mesh/", + "externalVersion": "", + "termCodeType": "STRING" + }, + { + "code": "organizations", + "label": "Organizations", + "description": "ICPSR Organization Authority List", + "adapter": "icpsr_thesaurus", + "termCodeType": "STRING", + "initParams": "10004" + }, + { + "code": "samplingProcedures", + "label": "Sampling Procedures", + "description": "DDI Sampling Procedure Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/SamplingProcedure", + "externalVersion": "1.1.4", + "termCodeType": "STRING", + "initParams": "SamplingProcedure" + }, + { + "code": "smallestGeographicUnits", + "label": "Smallest Geographic Units", + "description": "ICPSR Smallest Geographic Unit Controlled Vocabulary", + "adapter": "tree", + "termCodeType": "STRING" + }, + { + "code": "timeMethods", + "label": "Time Methods", + "description": "DDI Time Method Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/TimeMethod", + "externalVersion": "1.2.3", + "termCodeType": "STRING", + "initParams": "TimeMethod" + }, + { + "code": "analysisUnits", + "label": "Units of Analysis", + "description": "DDI Units of Analysis Controlled Vocabulary", + "adapter": "ddi", + "externalURI": "https://vocabularies.cessda.eu/vocabulary/AnalysisUnit", + "externalVersion": "2.1.3", + "termCodeType": "STRING", + "initParams": "AnalysisUnit" + }, + { + "code": "ror", + "label": "Research Organization Registry", + "description": "Research Organization Registry", + "adapter": "ror_proxy", + "termCodeType": "STRING" + }, + { + "code": "orcid", + "label": "ORCID", + "description": "ORCID", + "adapter": "orcid_proxy", + "termCodeType": "STRING" + }, + { + "code": "geographicNames", + "label": "Geographic Names", + "description": "ICPSR Geographic Names Thesaurus", + "adapter": "icpsr_thesaurus", + "termCodeType": "STRING", + "initParams": "10003" + }, + { + "code": "geoNames", + "label": "GeoName Terms", + "description": "GeoName Terms", + "adapter": "geonames_proxy", + "termCodeType": "STRING" + }, + { + "code": "oversamples", + "label": "Oversamples", + "description": "ICPSR Oversamples Controlled Vocabulary", + "adapter": "tree", + "termCodeType": "STRING" + }, + { + "code": "contributorTypes", + "label": "Contributor Types", + "description": "ICPSR Contributor Types Controlled Vocabulary", + "adapter": "tree", + "termCodeType": "STRING" + }, + { + "code": "psidLicense", + "label": "PSID License", + "description": "PSID (Panel Study of Income Dynamics) Public Data Extract License", + "adapter": "tree", + "termCodeType": "STRING" + }, + { + "code": "adaAccessibility", + "label": "ADA Accessibility", + "description": "ICPSR ADA Accessibility Status Controlled Vocabulary", + "adapter": "tree", + "termCodeType": "STRING" + } +] \ No newline at end of file diff --git a/resources/generate_markdown.py b/resources/generate_markdown.py new file mode 100644 index 0000000..1b2fab0 --- /dev/null +++ b/resources/generate_markdown.py @@ -0,0 +1,696 @@ +import json +from pathlib import Path +from datetime import datetime +import yaml +import sys +import argparse + +class QuoteDumper(yaml.SafeDumper): + pass + +def quoted_str_representer(dumper, data): + return dumper.represent_scalar("tag:yaml.org,2002:str", data, style='"') + +QuoteDumper.add_representer(str, quoted_str_representer) + +# ---------------------------- +# Configuration +# ---------------------------- + +SKIP_FILES = { + "common_data_elements.json", + "contributors.json", + "deposits.json", + "extent_of_processing.json", + "external_source_id.json", + "languages.json", + "link_title.json", + "link_url.json", + "oversamples.json", + "restrictions.json", + "study_purpose.json" +} + +PROCESSING_ORDER = [ + "title", + "alternate_titles", + "principal_investigators", + "funding_sources", + "summary", + "icpsr_subject_terms", + "jel_classifications", + "mesh_subject_terms", + "time_periods", + "nationally_representative_sample", + "geographic_coverage_areas", + "smallest_geographic_unit", + "study_design", + "universe", + "time_methods", + "units_of_analysis", + "sampling_procedures", + "sampling_note", + "weight", + "response_rates", + "data_source_types", + "external_data_sources", + "collection_modes", + "collection_dates", + "variable_description", + "scales", + "data_management_plan", + "preregistration", + "software_applications", + "general_data_formats", + "notes", + "manuscript_number", + "ada_accessibility", + "license", + "version_history", + "distributors", + "study_number", + "doi", + "citation", + "person", + "organization" +] + +# ---------------------------- +# Utilities +# ---------------------------- + +def anchor(text): + return text.lower().replace(" ", "-").replace("_", "-") + +def convert_example_to_titles(data, schema): + """ + Recursively replace property keys with schema 'title' values. + Works for objects and arrays of objects. + """ + if isinstance(data, dict): + props = schema.get("properties", {}) + result = {} + + for key, value in data.items(): + prop_schema = props.get(key, {}) + title = prop_schema.get("title", key.replace("_", " ").title()) + + result[title] = convert_example_to_titles(value, prop_schema) + + return result + + elif isinstance(data, list): + items_schema = schema.get("items", {}) + return [convert_example_to_titles(item, items_schema) for item in data] + + else: + return data + +def render_yaml_examples(examples, schema): + md = [] + + for ex in examples: + + # strings stay unchanged + if isinstance(ex, (str, int, float)): + md.append("```text") + md.append(f'"{ex}"') + md.append("```\n") + continue + + # list containing only simple values (strings or numbers) + if isinstance(ex, list) and all(isinstance(i, (str, int, float)) for i in ex): + md.append("```text") + for item in ex: + md.append(f'"{item}"') + md.append("```\n") + continue + + # convert keys to titles + human_ex = convert_example_to_titles(ex, schema) + + # dump YAML normally + #yaml_str = yaml.safe_dump(human_ex, sort_keys=False) + + # dump YAML; enclose everything in quotes + yaml_str = yaml.dump(human_ex, Dumper=QuoteDumper, sort_keys=False) + yaml_str = yaml_str.replace("\n...\n", "\n").rstrip(".\n") + + # insert a blank line between top-level list items + if isinstance(human_ex, list): + lines = yaml_str.splitlines() + new_lines = [] + for i, line in enumerate(lines): + new_lines.append(line) + # if the next line starts a new '- ', insert a blank line + if i + 1 < len(lines) and lines[i + 1].startswith("- "): + new_lines.append("") # blank line between items + yaml_str = "\n".join(new_lines) + + md.append("```yaml") + md.append(yaml_str) + md.append("```\n") + + return md + +def add_table_usageNotes(md_table, old_usage_note): + + # set up header and table for later use + header = "This field employs a local ICPSR controlled vocabulary; see below for terms and definitions:" + if old_usage_note: + usage_notes = [old_usage_note, "\n", header, "\n", *md_table, "\n"] + else: + usage_notes = [header, "\n", *md_table, "\n"] + + return usage_notes + +def get_schema_values(note, term, ROOT): + """ + Returns usage notes text for a property. + Supports either inline string or $ref to local YAML file. + """ + if isinstance(note, str): + return note # inline text + + if isinstance(note, dict) and "$ref" in note: + ref = note["$ref"] + # Extract filename from URL, e.g., summary + filename = ref.split("notes/")[-1].split("#")[0].rstrip("/") + notes_file = Path(ROOT, "notes", f"{filename}.yaml") + if notes_file.exists(): + with open(notes_file, "r", encoding="utf-8") as f: + data = yaml.safe_load(f) + match = data.get(term) + + return match.strip() if match else None + + return None + +def cv_to_table(cv_name, ROOT): + cv_file = Path(ROOT / "vocab_preset" / "data" / f"{cv_name}.json") + # return None if there is no matching CV + if not cv_file.is_file(): + return None + + # otherwise, build Markdown table of terms + with cv_file.open("r", encoding="utf-8") as f: + cv_data = json.load(f) + + has_paths = any('path' in obj for obj in cv_data) + + temp_md = [] + temp_md.append("| Term | Definition |") + temp_md.append("|------|------------|") + + for item in cv_data: + if has_paths and not item.get("path"): + continue + term = item.get("label", "") + definition = item.get("description", "") + temp_md.append(f"| {term} | {definition} |") + return temp_md + +def type_label(t): + mapping = { + "string": "Text", + "integer": "Number", + "boolean": "Boolean", + "object": "Multi-part element; see subfields", + "array": "Array" + } + return mapping.get(t, t or "") + +def get_ref(prop): + if "$ref" in prop: + return prop["$ref"] + + if prop.get("type") == "array": + items = prop.get("items", {}) + if "$ref" in items: + return items["$ref"] + + return None + +def resolve_ref_property(prop): + """ + Normalize $ref-based person/organization properties. + Returns (title, description, type, ref_title) + """ + ref = get_ref(prop) + + if ref and ( + "property_banks/person/" in ref or + "property_banks/organization/" in ref + ): + name = ref.split("/")[-3] if "/version/" in ref else ref.split("/")[-1] + + ref_title = name.replace("_", " ").title() + ref_desc = f"See the [{ref_title}](#{anchor(ref_title)}) field." + + title = prop.get("title", ref_title) + desc = prop.get("description", ref_desc) + typ = "Multi-part element; see subfields" + + return title, desc, typ, ref_title + + return None + +def ref_to_link(ref): + """ + Convert schema $ref → markdown link + """ + name = ref.split("/")[-3] if "/version/" in ref else ref.split("/")[-1] + title = name.replace("_", " ").title() + return title, f"See the [{title}](#{anchor(title)}) field." + +# ---------------------------- +# Schema loading +# ---------------------------- + +def load_schemas(PROPERTY_DIR, mode): + schemas = {} + file_list = PROPERTY_DIR.glob("*.json") + + if mode == "legacy": + legacy_file_list = list(file_list) + if len(legacy_file_list) == 1: + f = Path(legacy_file_list[0]) + data = json.loads(f.read_text(encoding="utf-8")) + schemas = data['properties'] + + else: + for f in PROPERTY_DIR.glob("*.json"): + if f.name in SKIP_FILES: + continue + data = json.loads(f.read_text(encoding="utf-8")) + schemas[f.stem] = data + + return schemas + +# ---------------------------- +# Schema parsing +# ---------------------------- + +def get_subfields(schema): + """ + Normalize object + array-of-object schemas + """ + if schema.get("type") == "object": + return schema.get("properties", {}), schema.get("required", []) + if schema.get("type") == "array": + items = schema.get("items", {}) + if items.get("type") == "object": + return items.get("properties", {}), items.get("required", []) + return {}, [] + +def get_repeatable(schema): + return "Yes" if schema.get("type") == "array" else "No" + +def get_type(schema): + if schema.get("type") == "array": + item_type = schema.get("items", {}).get("type") + return type_label(item_type) if item_type else "Array" + return type_label(schema.get("type")) + +# ---------------------------- +# Rendering helpers +# ---------------------------- + +def get_conditional_required(schema): + """ + Detect oneOf-based required constraints. + """ + #Normalize object + if schema.get("type") == "array": + schema = schema.get("items", {}) + + conditional_map = {} + + for clause in schema.get("allOf", []): + if "oneOf" in clause: + options = clause["oneOf"] + + # collect required fields per option + groups = [] + for opt in options: + req = opt.get("required", []) + if req: + groups.append(req) + + if groups: + # flatten unique field names + all_fields = set(f for group in groups for f in group) + + # build readable label + label = " or ".join( + [", ".join(f.title() for f in g) for g in groups] + ) + + for field in all_fields: + conditional_map[field] = f"Conditional (must include either {label})" + elif "required" in clause: + # Handle regular required fields + for field in clause["required"]: + conditional_map[field] = "Yes" + + return conditional_map + +def render_examples(examples): + md = [] + for ex in examples: + md.append("```json") + if isinstance(ex, (dict, list)): + md.append(json.dumps(ex, indent=2)) + else: + md.append(str(ex)) + md.append("```\n") + return md + +def render_subfields(ROOT, mode, schema, properties, required, parent_anchor, level=4): + """ + Render subfields table AND detailed per-subfield sections with anchors and examples. + """ + md = [] + + conditional_required = get_conditional_required(schema) + + md.append(f"{'#' * level} Subfields:\n") + + # Table header + md.append("| Property | Required? | Repeatable? | Accepted Values | Description |") + md.append("|---|---|---|---|---|") + + # Table rows + for name, prop in properties.items(): + resolved = resolve_ref_property(prop) + if resolved: + title, desc, typ, _ = resolved + else: + title = prop.get("title", name.replace("_", " ").title()) + desc = prop.get("description", "") + typ = get_type(prop) + + #set variables + anchor_id = f"{parent_anchor}_{name}" + if name in required: + req_label = "Yes" + elif name in conditional_required: + val = conditional_required[name] + if "Conditional" in val: + req_label = "Conditional" + elif val == "Yes": + req_label = "Yes" + else: + req_label = "No" + else: + req_label = "No" + # build out table + md.append(f"| [{title}](#{anchor_id}) | {req_label} | " + f"{get_repeatable(prop)} | {typ} | {desc} |") + + md.append("") + + # ---- Per-subfield detailed sections ---- + for name, prop in properties.items(): + #check if this property is repeatable + rep = get_repeatable(prop) + + #check if this property is required (or conditionally required) + if name in required: + req = "Yes" + elif name in conditional_required: + req = conditional_required[name] + else: + req = "No" + + #check if we have a $ref keyword; handle accordingly + resolved = resolve_ref_property(prop) + if resolved: + title, desc, typ, ref_title = resolved + typ = f"Multi-part element; for more information, see the [{ref_title}](#{anchor(ref_title)}) field" + else: + title = prop.get("title", name.replace("_", " ").title()) + desc = prop.get("description", "") + typ = get_type(prop) + + anchor_id = f"{parent_anchor}_{name}" + md.append(f"") + md.append(f"{'#' * (level + 1)} {title}\n") + + md.append(f"**Description:** {desc}\n") + md.append(f"**Required:** {req}\n") + md.append(f"**Repeatable:** {rep}\n") + md.append(f"**Accepted Values:** {typ}\n") + + #check for usage note, but don't write just yet + usage_note = None + if "usageNotes" in prop: + usage_note = get_schema_values(prop['usageNotes'], "usageNotes", ROOT) + + if "controlledVocab" in prop: + if mode == "legacy": + controlledVocab = get_schema_values(prop['controlledVocab'], "controlledVocab", ROOT) + md.append(f"**Controlled Vocabulary:** {controlledVocab}\n") + else: + md_table = cv_to_table(prop['controlledVocab'], ROOT) + #if table, then update usageNote + if md_table: + usage_note = add_table_usageNotes(md_table, usage_note) + + if isinstance(usage_note, str): + md.append(f"**Usage Notes:** {usage_note}\n") + elif isinstance(usage_note, list): + usage_note[0] = "**Usage Notes:** " + usage_note[0] + md.extend(usage_note) + + if "icpsrGuidance" in prop: + icpsrGuidance = get_schema_values(prop['icpsrGuidance'], "icpsrGuidance", ROOT) + md.append(f"**ICPSR Input Guidance:** {icpsrGuidance}\n") + + # Recurse for nested subfields + subprops, subreq = get_subfields(prop) + if subprops: + md.extend(render_subfields(ROOT, mode, prop, subprops, subreq, anchor_id, level + 1)) + + # Examples per subfield + if "examples" in prop: + + schema_type = prop.get("type") + items_type = prop.get("items", {}).get("type") + + if schema_type == "object" or (schema_type == "array" and items_type == "object"): + md.append(f"#### Complete {title} Examples (with Subfields):\n") + else: + md.append("**Examples:**\n") + + md.extend(render_yaml_examples(prop["examples"], prop)) + + + return md + +def render_property(name, schema, ROOT, mode, TOP_LEVEL_REQUIRED): + md = [] + + title = schema.get("title", name.replace("_", " ").title()) + desc = schema.get("description", "") + required = "Yes" if name in TOP_LEVEL_REQUIRED else "No" + anchor_id = anchor(title) + + md.append(f"") + md.append(f"### {title}\n") + if desc: + md.append(f"**Description:** {desc}\n") + md.append(f"**Required:** {required}\n") + md.append(f"**Repeatable:** {get_repeatable(schema)}\n") + md.append(f"**Accepted Values:** {get_type(schema)}\n") + + # Check for additional keywords: controlledVocab and usageNotes + usage_note = None + if "usageNotes" in schema: + usage_note = get_schema_values(schema['usageNotes'], "usageNotes", ROOT) + + if "controlledVocab" in schema: + if mode == "legacy": + controlledVocab = get_schema_values(schema['controlledVocab'], "controlledVocab", ROOT) + md.append(f"**Controlled Vocabulary:** {controlledVocab}\n") + else: + md_table = cv_to_table(schema['controlledVocab'], ROOT) + #if table, then update usageNote + if md_table: + usage_note = add_table_usageNotes(md_table, usage_note) + + if isinstance(usage_note, str): + md.append(f"**Usage Notes:** {usage_note}\n") + elif isinstance(usage_note, list): + usage_note[0] = "**Usage Notes:** " + usage_note[0] + md.extend(usage_note) + + if "icpsrGuidance" in schema: + icpsrGuidance = get_schema_values(schema['icpsrGuidance'], "icpsrGuidance", ROOT) + md.append(f"**ICPSR Input Guidance:** {icpsrGuidance}\n") + + properties, required_subfields = get_subfields(schema) + if properties: + md.extend(render_subfields(ROOT, mode, schema, properties, required_subfields, anchor_id)) + + # Examples + schema_type = schema.get("type") + items_type = schema.get("items", {}).get("type") + + if "examples" in schema: + + schema_type = schema.get("type") + items_type = schema.get("items", {}).get("type") + + if schema_type == "object" or (schema_type == "array" and items_type == "object"): + md.append(f"#### Complete {title} Examples (with Subfields):\n") + else: + md.append("**Examples:**\n") + + md.extend(render_yaml_examples(schema["examples"], schema)) + + return md, { + "title": title, + "anchor": anchor_id, + "required": required, + "repeatable": get_repeatable(schema), + "type": get_type(schema), + "description": desc + } + +# ---------------------------- +# Main +# ---------------------------- + +def main(): + + parser = argparse.ArgumentParser(description="Generate Markdown from JSON Schema(s).") + parser.add_argument( + "--input", + help="Path to the project directory", + required=True + ) + parser.add_argument( + "--mode", + choices=["legacy", "current"], + default="directory", + help="Whether to process legacy or current ICPSR metadata schema.", + required=True + ) + args = parser.parse_args() + input_path = Path(args.input) + mode = args.mode + current_date = datetime.now().strftime('%B %d, %Y') + + if mode == "legacy": + TOP_LEVEL_REQUIRED = { + "title", + "principal_investigator", + "version", + "version_date", + "distributor", + "summary", + "subject_term", + "time_period", + "geographic_coverage_area", + "study_number", + "doi" + } + ROOT = input_path / "schema" + PROPERTY_DIR = ROOT + OUTPUT_FILE = input_path / "markdown" / "icpsr_legacy_schema.md" + version_file = input_path / "markdown" / "legacy_schema_version_history.md" + key_file = input_path / "markdown" / "legacy_schema_key.md" + intro_file = input_path / "markdown" / "legacy_schema_intro_text.md" + main_title = "# ICPSR Legacy Metadata Schema\n" + + else: + TOP_LEVEL_REQUIRED = { + "title", + "principal_investigators", + "time_periods", + "geographic_coverage_areas", + "icpsr_subject_terms", + "summary", + "study_number", + "doi" + } + ROOT = input_path / "rde_schema" + PROPERTY_DIR = ROOT / "property_bank" + OUTPUT_FILE = input_path / "markdown" / "icpsr_metadata_schema.md" + version_file = input_path / "markdown" / "schema_version_history.md" + key_file = input_path / "markdown" / "schema_key.md" + intro_file = input_path / "markdown" / "schema_intro_text.md" + main_title = "# ICPSR Metadata Schema\n" + + schemas = load_schemas(PROPERTY_DIR, mode) + + # exit if 'schemas' is empty: + if not schemas: + print(f"No schemas found in {PROPERTY_DIR} (using mode {mode})") + sys.exit(1) + sections = [] + toc = [] + + if mode == "current": + schema_items = [] + for key in PROCESSING_ORDER: + if key in schemas: + schema_items.append((key, schemas[key])) + # Add any remaining keys not in PROCESSING_ORDER at the end + for key in schemas: + if key not in PROCESSING_ORDER: + schema_items.append((key, schemas[key])) + else: + schema_items = schemas.items() + + for name, schema in schema_items: + try: + md, entry = render_property(name, schema, ROOT, mode, TOP_LEVEL_REQUIRED) + except TypeError: + print(name) + sys.exit(1) + sections.extend(md) + sections.append("\n---\n") + toc.append(entry) + + # pull in text from files + intro_text = intro_file.read_text(encoding="utf-8").splitlines() + key_text = key_file.read_text(encoding="utf-8").splitlines() + version_text = version_file.read_text(encoding="utf-8").splitlines() + + output = [] + output.append(main_title) + output.append(f"Last updated: {current_date}\n\n") + output.extend(intro_text) + + # Add over table + output.append("## Metadata Elements: Overview\n") + output.append("| Property | Required? | Repeatable? | Accepted Values | Description |") + output.append("|---|---|---|---|---|") + + for e in toc: + output.append( + f"| [{e['title']}](#{e['anchor']}) | " + f"{e['required']} | " + f"{e['repeatable']} | " + f"{e['type']} | " + f"{e['description']} |" + ) + output.append("\n---\n") + + # add key to understand documentation + output.extend(key_text) + + # add detailed metadata information + output.append("\n---\n## Metadata Elements: Detailed Information\n") + output.extend(sections) + + # Add version history information + output.extend(version_text) + + OUTPUT_FILE.write_text("\n".join(output), encoding="utf-8") + print(f"Markdown generated: {OUTPUT_FILE}") + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/resources/generate_markdown_schema.py b/resources/generate_markdown_schema.py deleted file mode 100644 index 74eb707..0000000 --- a/resources/generate_markdown_schema.py +++ /dev/null @@ -1,424 +0,0 @@ -#!/usr/bin/python3 -""" Dereferences $ref elements in schema files, replacing the $ref with the contents - of the referenced schema file. Then generates and cleans up a markdown file - - Assumptions: - 1. $ref elements point only to YAML files. - 2. Every YAML file has a $schema element identifying the file as a JSON Schema. - 3. Every YAML file has an $id element that can serve as the target of any $ref. -""" -import os -import sys -import json -import yaml -import logging -import argparse -import subprocess -import datetime -import shutil -import re - -from glob import glob -from urllib.parse import urlparse, parse_qs - -logging.basicConfig(format='%(levelname)s: %(message)s', level=logging.INFO) -log = logging.getLogger() - -def get_cli_arguments(): - """ Parse command line arguments and return an object whose members contain the argument values. """ - parser = argparse.ArgumentParser(description="Generate markdown from JSON Schema and YAML files") - parser.add_argument('--source-dir', dest='source_dir', type=str, help='Source directory', required=True) - return parser.parse_args() - -def load_cache(root_dir): - """ Walks the file system from root_dir and loads any RDE schema files into a dict - keyed by the $id of the schema. - """ - cache = {} - schema_files = glob(os.path.join(root_dir, 'schema', '*.json'), recursive=True) - yaml_files = glob(os.path.join(root_dir, 'schema', 'yaml', '*.yaml'), recursive=True) - - for file_name in schema_files + yaml_files: - try: - with open(file_name, "r", encoding="utf-8") as f: - if ".json" in file_name: - content = json.load(f) - elif ".yaml" in file_name: - content = yaml.safe_load(f) - if content.get('usageNotes'): - content['usageNotes'] = content['usageNotes'].replace('\n', ' \n') - if content.get('curatorNotes'): - content['curatorNotes'] = content['curatorNotes'].replace('\n', ' \n') - - if '$schema' in content: # Use presence of $schema attribute to identify JSON Schema files - log.debug(f"Loading {file_name} into schema cache") - if (ident := content['$id']) not in cache: - cache[ident] = content - else: - raise ValueError(f"Schema file {file_name} uses an $id value ({ident}) that is already in use by another schema") - except KeyError as ex: - raise KeyError(f"Schema file {file_name} does not contain an $id field") from ex - return cache - -def dereference_cache(cache): - """ Deferences $ref values in the cache. """ - for key, schema in cache.items(): - log.debug(f"Dereferencing $ref values in schema: {key}") - cache[key] = resolve(schema, cache) - return cache - -def resolve(obj, cache): - """ Recursively deferences $ref values in a schema. """ - if isinstance(obj, dict): - new = {} - for key, value in obj.items(): - if key == "$ref": - try: - result = resolve(cache[value], cache) - new = {**new, **result} # Assumes that $ref always points to a dict - except KeyError as ex: - raise KeyError(f"Cannot find {value} in the schema cache") - elif key == "oneOf": - continue - else: - new[key] = resolve(value, cache) - return new - elif isinstance(obj, list): - return [resolve(item, cache) for item in obj] - else: - return obj - -def persist_cache(cache, temp_dir): - """ Persist cache to temp_dir """ - for key, schema in cache.items(): - if (title := schema.get('title')) is not None: - # path_components = urlparse(key).path.split('/') - # file_path = os.path.join(*path_components[1:]) # Remove first element, which is the base URI template - file_name = os.path.join(temp_dir, 'icpsr_study_schema.json') - os.makedirs(os.path.dirname(file_name), exist_ok=True) - - log.debug(f"Writing {title} schema to {file_name}") - - with open(file_name, 'w', encoding='utf-8') as fp: - json.dump(schema, fp, indent=4) - - elif 'yaml' not in key: - raise ValueError(f"Cannot persist schema because it does not contain a title element: {key}") - - return file_name - -def clean_label(label): - - return label.replace('_', ' ').title().replace("To", "to").replace("Of", "of").replace("Id", "ID").replace("Doi", "Digital Object Identifier (DOI)").replace("IDentifier", "Identifier").replace("Sda ", "SDA ").replace(" Url", " URL") - -def check_write(line, fo, processed_lines, index="foo"): - if isinstance(index, int): - if index not in processed_lines: - #write line to file-out (fo) - fo.write(line) - - #add index to list - processed_lines.append(index) - - else: - pass - - return processed_lines - - else: - fo.write(line) - -def fix_arrays(term, content): - found_targets = found_targets = [] - index = 0 # Initialize the index - - while index < len(content): - # Check if the line contains 'term' - if term in content[index]: - # Search for 'autogenerated_heading item' after the current index - for next_index in range(index + 1, len(content)): - if all(keyword in content[next_index] for keyword in ('autogenerated_heading', 'items')): - found_targets.append(next_index) # Store the index of the target line - break # Exit the inner loop once you've found the target - # Move the index to the next line - index += 1 - # If both keywords were found, add the current index too - - else: - # Move to the next line - index += 1 - - if term in ['**Type**: `array of enum (of string)`', '**Type**: `array of string`']: - for val in found_targets: - for i in range(4): - content[val+i] = 'SKIP\n' - - elif term in ['**Type**: `array of object`']: - for val in found_targets: - content[val] = content[val].replace(' items', ' Subfields:') - content[val+2] = 'SKIP\n' - content[val+3] = 'SKIP\n' - - return content - -def clean_data_type(data_type): - if 'string' in data_type: - new_data_type = ' Text' - elif 'integer' in data_type: - new_data_type = ' Number' - elif 'object' in data_type: - new_data_type = ' Multi-part; see subfields' - else: - new_data_type = data_type - - substring_to_replace = data_type.rstrip() - - # Calculate the length of the original substring - original_length = len(substring_to_replace) - - # Create the replacement string - adjusted_replacement = new_data_type + ' ' * (original_length - len(new_data_type)) - - # Replace the original substring with the adjusted replacement string - result_string = data_type.replace(substring_to_replace, adjusted_replacement) - - return result_string - -def get_schema_description(source_dir): - # Specify the path to your JSON file - json_file_path = os.path.join(source_dir, 'schema', 'icpsr_study_schema.json') - - # Open and parse the JSON file - with open(json_file_path, 'r') as json_file: - data = json.load(json_file) - - # Access the value of the first 'description' key - description_value = data.get('description') - - return description_value - -def main(): - """ Main entrypoint. """ - # source_dir == the main project directory. Must contain a 'schema' folder - try: - args = get_cli_arguments() - - if not os.path.exists(args.source_dir): - print(f"{args.source_dir} does not exist. Please verify path and try again") - sys.exit(1) - - #set up variables - site_dir = os.path.join(args.source_dir, 'site') - markdown_dir = os.path.join(args.source_dir, 'markdown') - resource_dir = os.path.join(args.source_dir, 'resources') - temp_dir = os.path.join(args.source_dir, 'temp') - mkdocs_yml = os.path.join(resource_dir, 'mkdocs.yml') - rtd_css = os.path.join(resource_dir, 'readthedocs_theme.css') - metadata_key = os.path.join(resource_dir, 'key.md') - - for folder in [temp_dir, site_dir, markdown_dir]: - if not os.path.exists(folder): - os.makedirs(folder) - - #produce a dereferenced json file - print("\tProducing cache...") - cache = dereference_cache(load_cache(args.source_dir)) - print("\tSaving temp file...") - dereferenced_file = persist_cache(cache, temp_dir) - - #remove extra $id and $schema values - print("\tRemoving extra $id and $schema values...") - with open(dereferenced_file, "r", encoding="utf-8") as f: - content = json.load(f) - - #remove additional $id and $schema entries - for k, v in content.items(): - for key, value in content['properties'].items(): - content['properties'][key].pop('$id', None) - content['properties'][key].pop('$schema', None) - - #write back to dereferenced json - with open(dereferenced_file, "w", encoding="utf-8") as f: - json.dump(content, f, indent=4) - - #generate markdown using modified version of JSON Schema for Humans - print("\tCreating markdown...") - md_file = os.path.join(markdown_dir, "icpsr_study_schema.md") - - cmd = "generate-schema-doc --config custom_template_path={} --config show_toc=false --config show_breadcrumbs=false {} {}".format(os.path.join(resource_dir, 'template', 'base.md'), dereferenced_file, md_file) - - subprocess.run(cmd, shell=True, text=True) - - #now read in all our schema markdown to make final improvements - print("\tFixing labels...") - with open(md_file, 'r', encoding='utf-8') as fi: - content=fi.readlines() - - #update schema description to include date - current_date=datetime.datetime.now() - content.insert(2, "Last updated: {}\n\n".format(current_date.strftime('%B %d, %Y'))) - - #fix array references - for term in ['**Type**: `array of enum (of string)`', '**Type**: `array of string`', '**Type**: `array of object`']: - content = fix_arrays(term, content) - - #set variables - property_dict = {} - pattern = r'\[([^\]]+)\]\(#([^\)]+)\)' - anchor_pattern = r'#+\s*' - processed_lines = [] - description_value = get_schema_description(args.source_dir) - first_heading = True - example_count = 0 - - #loop through content and fix various issues - with open(md_file, 'w', encoding='utf-8') as fo: - for index, line in enumerate(content): - #need to insert - - #build dict of components; look for markdown tables that include property definitions - if line.startswith('| [') and line.count('|') == 6: - #split on pipe; [1]=label/anchor, [2]=required?, [3]=repeatable, [4]=data type - parts = line.split('|') - match = re.search(pattern, parts[1]) - if match: - orig_label = match.group(1) - cleaned_label = clean_label(orig_label.strip()) - prop_name = match.group(2).strip() - - #create a dictionary entry; use the property name as key and manditoriness as value (yes/no) - property_dict[prop_name] = {"mandatory": parts[2].strip(), "repeatable": parts[3].strip(), "data_type": parts[4], "orig_label": orig_label, "cleaned_label": cleaned_label} - - #clean up data types - new_data_type = clean_data_type(property_dict[prop_name]['data_type']) - - line = line.replace(f'[{orig_label}]', f'[{cleaned_label}]').replace(property_dict[prop_name]['data_type'], new_data_type) - processed_lines = check_write(line, fo, processed_lines, index) - - elif "##" in line and "') - text[1] = text[1].replace(entry['orig_label'], entry['cleaned_label']).replace('[optional]', '').replace('[required]', '') - anchor_line = ''.join(text) - - #we will add an extra '#' to headings - anchor_line = '#' + anchor_line - - processed_lines = check_write(anchor_line, fo, processed_lines, index) - check_write("\n", fo, processed_lines) - - # We are going to assume that there is a description associated with every property; skip 2 index spaces to write description - description_line = content[index+2] - processed_lines = check_write(description_line, fo, processed_lines, index+2) - - #account for newline after description - processed_lines = check_write("\n", fo, processed_lines, index+3) - - #add required? statement - check_write(f"**Required**: {entry['mandatory']}\n\n", fo, processed_lines) - - #add repeatable? statement - check_write(f"**Repeatable**: {entry['repeatable']}\n", fo, processed_lines) - - #If this is a main element, get name for later use with subfield example heading, if needed - if line.startswith("## "): - current_element = entry['cleaned_label'] - - elif line.startswith("**Type**"): - data_type = line.split(':')[1].strip().replace('`', '') - - #check for specific format_type rules - format_type = '' - if content[index+2].startswith("**Format**:"): - format_type = content[index+2].split(':')[1].strip().replace('`', '').replace('uri', 'URL') - - #add format line and following new line to processed_lines - processed_lines.extend([index+2, index+3]) - - if 'string' in data_type: - accepted_value = 'Text' - if len(format_type) > 0: - accepted_value += f" (formatted as a {format_type})" - elif 'integer' in data_type: - accepted_value = 'Number' - elif 'object' in data_type: - accepted_value = 'Multi-part element; see subfield definitions for more information.' - - processed_lines = check_write(f"**Accepted Values**: {accepted_value}\n", fo, processed_lines, index) - - elif '**Additional properties**: [[Not allowed]](# "Additional Properties not allowed.")' in line: - processed_lines.append(index) - processed_lines.append(index+1) - - elif line.startswith('SKIP'): - processed_lines.append(index) - - elif description_value in line: - processed_lines = check_write(line, fo, processed_lines, index) - processed_lines = check_write('\n', fo, processed_lines, index+1) - check_write('For a machine-actionable copy of this information, please see the [JSON Schema version](https://github.com/ICPSR/metadata/blob/main/schema/icpsr_study_schema.json).\n\n## Metadata Elements: Overview\n\n', fo, processed_lines) - - #check to see if this is the second 'example' in a given section--if so, change the heading so that it's clear this is a full example with all subfields - elif line.startswith('**Example'): - #Add one to our example count - example_count += 1 - #if our count is now at 2 it means we have consecutive 'Example' sections under one heading. Adjust the label. If count is at one, just write the line to file-out. - if example_count > 1: - processed_lines = check_write(f'###### Complete {current_element} Examples (with Subfields):', fo, processed_lines, index) - else: - processed_lines = check_write(line, fo, processed_lines, index) - - else: - processed_lines = check_write(line, fo, processed_lines, index) - - #now let's add our version history; first insert a blank line - fo.write('\n') - version_history_file = os.path.join(markdown_dir, "version_history.md") - with open(version_history_file, 'r', encoding='utf-8') as f: - version_lines = f.readlines() - - for v in version_lines: - fo.write(v) - - #remove temp folder - print("\n\nRemoving temp folder...") - shutil.rmtree(temp_dir, ignore_errors=True) - print("\nAll done!") - - except Exception as ex: # pylint: disable=broad-except - log.error(ex) - sys.exit(1) - -if __name__=='__main__': - main() diff --git a/resources/mkdocs.yml b/resources/mkdocs.yml index 1178bc3..d33d153 100644 --- a/resources/mkdocs.yml +++ b/resources/mkdocs.yml @@ -1,10 +1,11 @@ -site_name: Metadata Documentation Portal +site_name: ICPSR Metadata Documentation Portal site_url: https://icpsr.github.io/metadata/ docs_dir: ../markdown site_dir: ../site nav: - Home: index.md - - ICPSR Metadata Schema: icpsr_study_schema.md + - ICPSR Metadata Schema: icpsr_metadata_schema.md + - ICPSR Legacy Metadata Schema: icpsr_legacy_schema.md - ICPSR Metadata Style Guide: icpsr_style_guide.md - ICPSR Metadata Export API: icpsr_metadata_api.md - ICPSR Metadata Change Process: request_change.md @@ -18,6 +19,10 @@ theme: navigation_depth: 3 sticky_navigation: true include_homepage_in_sidebar: false +plugins: + - redirects: + redirect_maps: + 'icpsr_study_schema.md': 'icpsr_legacy_schema.md' extra_css: - assets/style.css extra_javascript: diff --git a/resources/readthedocs_theme_extra.css b/resources/readthedocs_theme_extra.css index c5a92a2..06975ed 100644 --- a/resources/readthedocs_theme_extra.css +++ b/resources/readthedocs_theme_extra.css @@ -120,6 +120,11 @@ form .search-query { background: rgba(255, 255, 255, 0.7); } +/* Underline links in content areas */ +.rst-content a { + text-decoration: underline; +} + /* * Account for wide tables which go off the side. * Override borders to avoid weirdness on narrow tables. diff --git a/resources/requirements.txt b/resources/requirements.txt index d388731..532c0a4 100644 --- a/resources/requirements.txt +++ b/resources/requirements.txt @@ -1,3 +1,4 @@ pyyaml~=6.0.1 mkdocs~=1.5.2 +mkdocs-redirects~=1.2 git+https://github.com/shallcro/jsfh-revised.git@acf3dbe5d16e9c9512f877a1d7b2cc872093ee87 \ No newline at end of file diff --git a/resources/run_mkdocs.py b/resources/run_mkdocs.py index 700301b..a057292 100644 --- a/resources/run_mkdocs.py +++ b/resources/run_mkdocs.py @@ -24,20 +24,14 @@ def main(): site_dir = os.path.join(args.source_dir, 'site') resource_dir = os.path.join(args.source_dir, 'resources') mkdocs_yml = os.path.join(resource_dir, 'mkdocs.yml') - # rtd_css = os.path.join(resource_dir, 'readthedocs_theme.css') - # rtd_extra_css = os.path.join(resource_dir, 'readthedocs_theme_extra.css') if not os.path.exists(site_dir): os.makedirs(site_dir) #generate html; run mkdocs - cmd = 'mkdocs build -f {} --clean --verbose'.format(mkdocs_yml) + cmd = f'mkdocs build -f {mkdocs_yml} --clean --verbose' subprocess.run(cmd, shell=True) - #add improved CSS - # shutil.copy(rtd_css, os.path.join(site_dir, 'css', 'theme.css')) - # shutil.copy(rtd_extra_css, os.path.join(site_dir, 'css', 'theme_extra.css')) - except Exception as ex: # pylint: disable=broad-except sys.exit(1) diff --git a/schema/icpsr_study_schema.json b/schema/icpsr_legacy_schema.json similarity index 89% rename from schema/icpsr_study_schema.json rename to schema/icpsr_legacy_schema.json index 9867ff6..bf60380 100644 --- a/schema/icpsr_study_schema.json +++ b/schema/icpsr_legacy_schema.json @@ -1,20 +1,22 @@ { "$schema": "https://json-schema.org/draft-07/schema#", "$id": "https://schemas.icpsr.umich.edu/schema/icpsr_study_schema?version=v1", - "title": "ICPSR Metadata Schema", - "description": "This is the metadata schema used to describe data collections at the Inter-university Consortium for Political and Social Research (ICPSR). These rules and definitions represent ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help ICPSR users -- including data depositors and researchers accessing data -- understand how to use and interpret our metadata.", + "title": "ICPSR Legacy Metadata Schema", + "description": "This metadata schema has been used to describe curated data collections at the Inter-university Consortium for Political and Social Research (ICPSR) through approximately 2026. Beginning in 2026, it is being phased out and replaced by an updated metadata schema. These rules and definitions document ICPSR's metadata practices and are intended to (a) assist ICPSR staff with metadata entry, and (b) help users – including data depositors and researchers – understand and interpret ICPSR metadata.", "type": "object", "required": [ "title", "principal_investigator", "version", "version_date", "distributor", "summary", "subject_term", "time_period", "geographic_coverage_area", "study_number" ], "additionalProperties": false, "properties": { "version": { + "title": "Version", "description": "The current version number for the data collection.", "type": "integer", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/version?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/version#/usageNotes"}, "examples": [ 1, 2 ] }, "version_date": { + "title": "Version Date", "description": "The date on which the current version of the data collection was released by ICPSR.", "type": "string", "format": "date", @@ -23,6 +25,7 @@ "examples": [ "2006-03-30", "2019-05-05" ] }, "original_release_date": { + "title": "Original Release Date", "description": "The date on which the data collection was originally released by ICPSR.", "type": "string", "format": "date", @@ -31,10 +34,11 @@ "examples": [ "2001-02-07", "2020-08-12" ] }, "title": { + "title": "Title", "description": "The official title that describes what the data collection is about, its geographic scope, and the time period it covered.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/title?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/title#/usageNotes"}, "examples": [ "Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project, Kansas City, Missouri, 2014-2017", "Health and Relationships Project, United States, 2014-2015", @@ -44,6 +48,7 @@ ] }, "alternate_title": { + "title": "Alternate Title", "description": "The alternate name(s) or acronym(s) commonly used to refer to the data collection.", "type": "array", "items": { @@ -59,6 +64,7 @@ ] }, "link_title": { + "title": "Link Title", "description": "The title of an external resource that is included in the ICPSR catalog as a courtesy to users.", "type": "string", "controlledVocab": "N/A", @@ -66,6 +72,7 @@ "examples": [ "Cebu Longitudinal Health and Nutrition Survey" ] }, "link_url": { + "title": "Link URL", "description": "The URL of an external resource that is included in the ICPSR catalog as a courtesy to users.", "type": "string", "controlledVocab": "N/A", @@ -73,48 +80,54 @@ "examples": [ "https://cebu.cpc.unc.edu/" ] }, "principal_investigator": { + "title": "Principal Investigator", "description": "The key people or organizations responsible for the data collection, listed by importance. Each data collection requires at least one PI, either a person or an organization.", "type": "array", "controlledVocab": "The [ICPSR Personal Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10002) and [Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) are the primary authority control sources for PI names. The [Virtual International Authority File](https://viaf.org/) (VIAF) serves as a secondary resource if names are not present in ICPSR lists.", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/pi_names?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/pi_names#/usageNotes"}, "items": { "type": "object", "properties": { "person": { + "title": "Person", "description": "The name of a person primarily responsible for the data collection.", "type": "object", "properties": { "given_name": { + "title": "Given (First) Name", "description": "The person's given name.", - "type": "string" + "type": "string", + "examples": [ + "James A.", "Lois", "E.V." + ] }, "family_name": { + "title": "Family (Last) Name", "description": "The person's family name (e.g., surname).", - "type": "string" + "type": "string", + "examples": [ + "McCann Jr.", "Smith", "Oppenhuis" + ] } }, "required": ["given_name", "family_name"], - "additionalProperties": false, "examples": [ { "given_name": "James A.", - "family_name": "McCann" + "family_name": "McCann Jr." }, { - "given_name": "Warren", - "family_name": "Winkelstein Jr." + "given_name": "Lois", + "family_name": "Smith" }, { "given_name": "E.V.", "family_name": "Oppenhuis" - }, - { - "given_name": "Miner P.", - "family_name": "Marchbanks III" } ] }, "organization": { + "title": "Organization", "description": "The name of the organization primarily responsible for the data collection OR the organization with which an individual PI was affiliated at the time of a data collection's deposit at ICPSR.", "type": "string", "examples": [ @@ -125,6 +138,7 @@ ] }, "order": { + "title": "Order", "description": "The order or rank of importance for the PIs associated with the data collection, typically provided to ICPSR by the lead PI.", "type": "integer", "controlledVocab": "N/A", @@ -132,11 +146,17 @@ "examples": [1,2,3] } }, - "oneOf": [ - { "required": ["person"] }, - { "required": ["organization"] } + "allOf": [ + { + "oneOf": [ + { "required": ["person"] }, + { "required": ["organization"] } + ] + }, + { + "required": ["order"] + } ], - "required": ["order"], "additionalProperties": false }, "minItems": 1, @@ -168,22 +188,25 @@ ] }, "citation": { + "title": "Citation", "description": "The official way to reference the data collection in writing.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/citation?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/citation#/usageNotes"}, "examples": [ ["University of Michigan. Survey Research Center. Economic Behavior Program. Survey of Consumer Attitudes and Behavior, September 2018. Inter-university Consortium for Political and Social Research [distributor], 2021-11-18. https://doi.org/10.3886/ICPSR38121.v1"], ["Goldin, Claudia, and Lawrence Katz. The 1915 Iowa State Census Project. ICPSR28501-v1. Ann Arbor, MI: Inter-university Consortium for Political and Social Research [distributor], 2010-12-14. http://doi.org/10.3886/ICPSR28501.v1"] ] }, "distributor": { + "title": "Distributor", "description": "The organization(s) responsible for distributing the data collection.", "type": "array", "items": { "type": "object", "properties": { "name": { + "title": "Name", "description": "The name of the data distributor.", "type": "string", "controlledVocab": "[ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004)", @@ -193,6 +216,7 @@ ] }, "location": { + "title": "Location", "description": "The location of the data distributor.", "type": "string", "controlledVocab": "N/A", @@ -200,6 +224,7 @@ "examples": ["Ann Arbor, MI", "Chicago, IL"] }, "order": { + "title": "Title", "description": "The order of importance for the distributors of the data collection.", "type": "integer", "controlledVocab": "N/A", @@ -211,7 +236,7 @@ "additionalProperties": false }, "minItems": 1, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/distributor?version=v1", + "icpsrGuidance": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/distributor#/icpsrGuidance"}, "examples": [ [ { @@ -235,6 +260,7 @@ ] }, "study_number": { + "title": "Study Number", "description": "A unique, numerical value used by ICPSR to identify and track data collections.", "type": "integer", "controlledVocab": "N/A", @@ -242,6 +268,7 @@ "examples": [2760, 3025, 38672] }, "doi": { + "title": "Digital Object Identifier (DOI)", "description": "The registered persistent digital object identifier (DOI) associated with the data collection.", "type": "string", "format": "uri", @@ -250,16 +277,18 @@ "examples": [ "https://doi.org/10.3886/ICPSR03025.v2", "https://doi.org/10.3886/ICPSR06425.v1" ] }, "funding_source": { + "title": "Funding Source", "description": "The sources of funding that supported the data collection.", "type": "array", "items": { "type": "object", "properties": { "agency": { + "title": "Agency", "description": "An organization that supported the data collection.", "type": "string", "controlledVocab": "The [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004) is the primary authority control source for funding agencies. The [Virtual International Authority File](https://viaf.org/) (VIAF) serves as a secondary resource if names are not present in the ICPSR list.", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/funding_agency?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/funding_agency#/usageNotes"}, "icpsrGuidance": "The Principal Investigator's home institution does not need to be listed as a funding agency unless the PI provides a grant number (or other award information) or makes a specific request.", "examples": [ "United States Department of Justice. Office of Justice Programs. Bureau of Justice Statistics", @@ -268,6 +297,7 @@ ] }, "grant_number": { + "title": "Grant Number", "description": "A unique identifier associated with the funding.", "type": "array", "items": { @@ -282,13 +312,14 @@ ] }, "purpose": { + "title": "Purpose", "description": "The purpose of the funding.", "type": "array", "items": { "type": "string", "enum": ["collection and/or analysis of data", "secondary analysis of data", "archiving of data"] }, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/funding_purpose?version=v1", + "controlledVocab": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/funding_purpose#/controlledVocab"}, "icpsrGuidance": "This is an internal ICPSR element that is not publicly displayed. Certain ICPSR topical archives find this useful as they assemble reports for their funding agencies.", "examples": [ ["collection and/or analysis of data", "secondary analysis of data"], @@ -296,6 +327,7 @@ ] }, "order": { + "title": "Order", "description": "The relative order of funding sources associated with the data collection.", "type": "integer", "controlledVocab": "N/A", @@ -304,7 +336,7 @@ } }, "required": ["agency", "order"], - "dependentRequired": { "grant_numbers": ["agency"] }, + "dependentRequired": { "grant_number": ["agency"] }, "additionalProperties": false }, "examples": [ @@ -331,29 +363,32 @@ ] }, "external_source_ID": { + "title": "External Source ID", "description": "A unique identifier supplied by the data depositor.", "type": "array", "items": { "type": "string" }, "controlledVocab": "N/A", - "icpsrGuidance": "This is an internal ICPSR element that is not publicly displayed. An External Source ID consists of: an ICPSR-defined source organization code, a colon, and a Depositor-supplied ID.", + "icpsrGuidance": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/external_source_ID#/icpsrGuidance"}, "examples": [ ["BJS:271"], ["PSC:12345"] ] }, "summary": { + "title": "Summary", "description": "A description of the data collection that helps users understand its purpose, substance, and key topics.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/summary?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/summary#/usageNotes"}, "examples": [ "In 2014, Chicago Public Schools, looking to reduce the possibility of gun violence among school-aged youth, applied for a grant through the National Institute of Justice. CPS was awarded the Comprehensive School Safety Initiative grant and use said grant to establish the 'Connect and Redirect to Respect' program. This program used student social media data to identify and intervene with students thought to be at higher risk for committing violence. At-risk behaviors included brandishing a weapon, instigating conflict online, signaling gang involvement, and threats towards others. Identified at-risk students would be contacted by a member of the CPS Network Safety Team or the Chicago Police Department's Gang School Safety Team, depending on the risk level of the behavior. To evaluate the efficacy of CRR, the University of Chicago Crime Lab compared outcomes for students enrolled in schools that received the program to outcomes for students enrolled in comparison schools, which did not receive the program. 32 schools were selected for the study, with a total of 44,503 students. Demographic variables included age, race, sex, and ethnicity. Misconduct and academic variables included arrest history, in-school suspensions, out-of-school suspensions, GPA, and attendance days.", "The Health and Relationship Project is a study of both spouses in same-sex and different-sex marriages who were legally married and aged 35 to 65 at the time of data collection (2015). There are two parts of this study: a baseline questionnaire and a daily diary questionnaire completed for 10 consecutive days; both components were completed online and spouses were asked to complete the surveys separately. The baseline questionnaire asks participants about a number of topics related to marriage and health, including stress, health status and health behaviors, relationship quality, and how they have approached health problems in the past. The diary questionnaire asks participants a number of questions about the past 24 hours, including daily stress experiences, social interactions, and health behaviors." ] }, "subject_term": { + "title": "Subject Term", "description": "A controlled list of social science terms maintained by ICPSR and used to indicate topics related to the data collection.", "type": "array", "items": { @@ -370,6 +405,7 @@ ] }, "geographic_coverage_area": { + "title": "Geographic Coverage Area", "description": "The geographic locations where the data refer or are related.", "type": "array", "items": { @@ -377,7 +413,8 @@ }, "minItems": 1, "controlledVocab": "[ICPSR Geographic Names Thesaurus](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10003).", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/geographic_coverage_area?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/geographic_coverage_area#/usageNotes"}, + "icpsrGuidance": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/geographic_coverage_area#/icpsrGuidance"}, "examples": [ ["United States", "Maryland", "Baltimore"], ["United Kingdom", "China"], @@ -385,16 +422,18 @@ ] }, "time_period": { + "title": "Time Period", "description": "The time period(s) to which the data refer, regardless of when the data were collected.", "type": "array", "items": { "type": "object", "properties": { "date": { + "title": "Date", "description": "The date (or date range) for a time period to which the data refer.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/time_period_date?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/time_period_date#/usageNotes"}, "examples": [ "2020", "2021--2022", @@ -404,10 +443,11 @@ }, "time_frame": { + "title": "Time Frame", "description": "An optional free-text description of the time period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/time_period_time_frame?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/time_period_time_frame#/usageNotes"}, "examples": [ "Wave 1", "Spring 2013", @@ -436,12 +476,14 @@ ] }, "collection_date": { + "title": "Collection Date", "description": "The date(s) when the data were physically collected.", "type": "array", "items": { "type": "object", "properties": { "date": { + "title": "Date", "description": "The date (or date range) of the data collection period.", "type": "string", "controlledVocab": "N/A", @@ -454,10 +496,11 @@ ] }, "time_frame": { + "title": "Time Frame", "description": "An optional free-text description of the data collection period, used for non-numeric dates (e.g., 'Fall 2012') or to add context when multiple dates are present.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/collection_date_time_frame?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/collection_date_time_frame#/usageNotes"}, "examples": [ "Wave 1", "Spring 2013", @@ -486,6 +529,7 @@ ] }, "universe": { + "title": "Universe", "description": "The total group of persons or other entities (e.g., households or organizations) that were the object of research and to which analytic results refer.", "type": "string", "controlledVocab": "N/A", @@ -501,6 +545,7 @@ ] }, "data_type": { + "title": "Data Type", "description": "The types of data included in the data collection.", "type": "array", "items": { @@ -524,13 +569,14 @@ "video: film, animation, etc." ] }, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/data_type?version=v1", + "controlledVocab": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/data_type#/controlledVocab"}, "examples": [ ["administrative records data"], ["census/enumeration data", "survey data", "video: film, animation, etc."] ] }, "collection_note": { + "title": "Collection Note", "description": "Important details about the data collection (like unique authoring, discrepencies, or processing information) that can't be recorded in other metadata elements.", "type": "array", "items": { @@ -555,6 +601,7 @@ ] }, "study_purpose": { + "title": "Study Purpose", "description": "The study's main goals and associated research questions.", "type": "string", "controlledVocab": "N/A", @@ -566,15 +613,18 @@ ] }, "study_design": { + "title": "Study Design", "description": "The procedures used to contact participants and gather data.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/study_design?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/study_design#/usageNotes"}, + "icpsrGuidance": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/study_design#/icpsrGuidance"}, "examples": [ "Data on organizational culture in each of the 12 courts (Part 1) were obtained by administering the Court Culture Assessment Instrument (CCAI) to all judges with a felony criminal court docket and to all senior court administrators. A total of 224 respondents completed the questionnaire. The CCAI was used to assess five key dimensions of current court culture orientation: (1) dominant case management style, (2) judicial and court staff relations, (3) change management, (4) courthouse leadership, and (5) internal organization. The determination of what culture judges and court administrators desired to establish in the near future was also obtained through the application of the same instrument (CACI) as practitioners were asked to indicate the type of culture in each work area (or content dimension) they would like to see in their court in the next five years. Additionally, surveys were conducted of prosecuting attorneys (Part 2) and public defender attorneys (Part 3) to gauge their views on how well the courts in which they practice achieve the goals of access, fairness, and managerial effectiveness. Every prosecutor and public defender with two years or more experience in representing the state or criminal defendants in felony cases was asked to complete a questionnaire probing their thoughts on how well their court acted to promote access to records through availability and staff cooperation, treating litigants, witnesses, jurors and others fairly, and demonstrating concern for the rights and interests of others in the criminal trial process, including attorney and victims. A total of 334 prosecuting attorneys and 260 public defense attorneys completed the 46-item trial court process survey." ] }, "variable_description": { + "title": "Variable Description", "description": "Significant variables (particularly demographic variables) in the data files.", "type": "string", "controlledVocab": "N/A", @@ -585,6 +635,7 @@ ] }, "sampling": { + "title": "Sampling", "description": "The methods used to select the subset of the population that data are to be collected from (e.g., simple, systematic, stratified).", "type": "string", "controlledVocab": "N/A", @@ -610,6 +661,7 @@ ] }, "time_method": { + "title": "Time Method", "description": "The methods used to collect data over time, like snapshots at one point (cross-sectional) or repeatedly (longitudinal) to study changes or trends.", "type": "array", "items": { @@ -628,13 +680,14 @@ "Time Series: Discrete" ] }, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/time_method?version=v1", + "controlledVocab": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/time_method#/controlledVocab"}, "examples": [ ["Cross-sectional"], ["Longitudinal: Cohort / Event-based", "Time Series"] ] }, "data_source": { + "title": "Data Source", "description": "The source of the data, when that source is external to the data collection and can be independently cited.", "type": "array", "items": { @@ -656,6 +709,7 @@ ] }, "collection_mode": { + "title": "Collection Mode", "description": "The method(s) or procedure(s) used to collect the data.", "type": "array", "items": { @@ -683,13 +737,14 @@ "web-based survey" ] }, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/collection_mode?version=v1", + "controlledVocab": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/collection_mode#/controlledVocab"}, "examples": [ ["audio computer-assisted self interview (ACASI)"], ["computer-assisted self interview (CASI)", "face-to-face interview"] ] }, "extent_of_processing": { + "title": "Extent of Processing", "description": "Processing activities and checks performed on the data collection by ICPSR curation staff.", "icpsrGuidance": "This element is displayed to end-users in version history.", "type": "array", @@ -704,7 +759,7 @@ "Standardized missing values" ] }, - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/extent_of_processing?version=v1", + "controlledVocab": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/extent_of_processing#/controlledVocab"}, "examples": [ [ "Created variable labels and/or value labels.", @@ -717,6 +772,7 @@ ] }, "weight": { + "title": "Weight", "description": "The weight variables and the criteria for using them in data analysis or other information about how the data are weighted if no weight variables are present.", "type": "string", "controlledVocab": "N/A", @@ -728,6 +784,7 @@ ] }, "response_rates": { + "title": "Response Rates", "description": "The percentage of respondents in the sample who participated in the data collection.", "type": "string", "controlledVocab": "N/A", @@ -739,16 +796,18 @@ ] }, "scale": { + "title": "Scale", "description": "Any commonly known scales used to collect data for the data collection (e.g., MMPI, CPI, the Census Occupational Codes, etc.).", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/scale?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/scale#/usageNotes"}, "examples": [ ["The baseline data collection included one scale - the CES-D index for maternal depression [Cole, J. C., Rabin, A. S., Smith, T. L., and Kaufman, A. S. (2004). Development and validation of a Rasch-derived CES-D short form. Psychological assessment, 16(4), 360]. All scales used for outcomes at ages 1 through 3 are listed in Appendix Tables 1 and 2 in the User Guide. Please refer to the User Guide and P.I. Codebook, available under the 'Data and Documentation' tab, for details."], ["Squires, J., Bricker, D. D., and Twombly, E. (2009). Ages and stages questionnaires. Baltimore, MD: Paul H. Brookes.", "Briggs-Gowan, M. J., Carter, A. S., Irwin, J. R., Wachtel, K., and Cicchetti, D. V. (2004). The Brief Infant-Toddler Social and Emotional Assessment: screening for social-emotional problems and delays in competence. Journal of pediatric psychology, 29(2), 143-155.", "Yu, L., Buysse, D. J., Germain, A., Moul, D. E., Stover, A., Dodds, N. E., ... and Pilkonis, P. A. (2012). Development of short forms from the PROMIS sleep disturbance and sleep-related impairment item banks. Behavioral sleep medicine, 10(1), 6-24."] ] }, "unit_of_observation": { + "title": "Unit of Observation", "description": "The object(s) of analysis for the data collection, such as an organization, individual, or household.", "type": "array", "controlledVocab": "N/A", @@ -763,10 +822,12 @@ ] }, "smallest_geographic_unit": { + "title": "Smallest Geographic Unit", "description": "The smallest geographic unit (e.g., state or census tract) used in the dataset.", "type": "string", "controlledVocab": "N/A", - "$ref": "https://schemas.icpsr.umich.edu/schema/yaml/smallest_geographic_unit?version=v1", + "usageNotes": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/smallest_geographic_unit#/usageNotes"}, + "icpsrGuidance": {"$ref": "https://schemas.icpsr.umich.edu/schema/notes/smallest_geographic_unit#/icpsrGuidance"}, "examples": [ "state", "Census tract", @@ -774,6 +835,7 @@ ] }, "restrictions": { + "title": "Restrictions", "description": "Rules about how the data collection can be accessed or used.", "type": "string", "controlledVocab": "N/A", @@ -783,6 +845,7 @@ ] }, "membership_required": { + "title": "Membership Required", "description": "The availability of the data collection in terms of ICPSR membership. Members-only data may only be downloaded by affiliates of ICPSR member institutions who contribute funding to support the data.", "type": "boolean", "controlledVocab": "N/A", @@ -790,6 +853,7 @@ "examples": ["True", "False"] }, "restricted_access": { + "title": "Restricted Access", "description": "General indication of any access restrictions associated with the data collection. More detailed information is provided in the Restrictions element.", "type": "boolean", "controlledVocab": "N/A", @@ -797,6 +861,7 @@ "examples": ["True", "False"] }, "changes_to_collection": { + "title": "Changes to Collection", "description": "A record of how the data collection has changed over time.", "type": "array", "controlledVocab": "N/A", @@ -804,12 +869,14 @@ "type": "object", "properties": { "date": { + "title": "Date", "description": "The date on which an update occurred. ICPSR automatically generates this date.", "type": "string", "format": "date", "examples": [ "2006-03-30", "2019-05-05" ] }, "note": { + "title": "Note", "description": "An explanation of the nature of the update.", "type": "string", "examples": [ @@ -837,6 +904,7 @@ ] }, "series": { + "title": "Series", "description": "A named collection of related studies.", "type": "string", "controlledVocab": "[ICPSR Series](https://www.icpsr.umich.edu/web/ICPSR/search/series)", @@ -849,6 +917,7 @@ ] }, "classification": { + "title": "Classification", "description": "Topics used to organize data collections and help users explore the ICPSR catalog.", "type": "array", "items": { @@ -862,6 +931,7 @@ ] }, "filesets": { + "title": "Filesets", "description": "The grouping of files in the data collection.", "type": "array", "controlledVocab": "N/A", @@ -869,12 +939,14 @@ "type": "object", "properties": { "number": { + "title": "Number", "description": "A number that uniquely identifies a 'part' or component file that is associated with the data collection.", "type": "integer", "usageNotes": "Fileset numbers are typically (but not always) consecutive integers beginning with 1. (In some cases, the number may be drawn from an external resource, such as FIPS state and county codes.) The numbers correspond to the 'part numbers' embedded in ICPSR standard filenames.", "examples": [1, 2, 3] }, "name": { + "title": "Name", "description": "A brief title used to distinguish each fileset within a data collection.", "type": "string", "controlledVocab": "N/A", @@ -887,6 +959,7 @@ ] }, "sda_note": { + "title": "SDA Note", "description": "Additional information about the fileset for the purpose of helping online analysis users.", "type": "string", "controlledVocab": "N/A", @@ -900,7 +973,7 @@ "dependentRequired": { "name": ["number"] }, "additionalProperties": false }, - "usageNotes": "Filesets are used at ICPSR to make a convenient package for description, discovery, preservation and dissemination -- a package that is smaller than the data collection but larger than the individual file. A fileset typically contains a single file of statistical data plus additional files that support the data -- such as setups for statistical software, documentation, and alternative data representations. Every ICPSR data collection with at least one file must have at least one defined Fileset; a data collection may have multiple filesets. Each Fileset has a Number, and may also have a Name and an SDA (Survey Documentation and Analysis) Note.", + "usageNotes": "Filesets are used at ICPSR to make a convenient package for description, discovery, preservation and dissemination – a package that is smaller than the data collection but larger than the individual file. A fileset typically contains a single file of statistical data plus additional files that support the data – such as setups for statistical software, documentation, and alternative data representations. Every ICPSR data collection with at least one file must have at least one defined Fileset; a data collection may have multiple filesets. Each Fileset has a Number, and may also have a Name and an SDA (Survey Documentation and Analysis) Note.", "examples": [ [ { @@ -931,4 +1004,4 @@ ] } } -} +} \ No newline at end of file diff --git a/schema/yaml/citation.yaml b/schema/notes/citation.yaml similarity index 66% rename from schema/yaml/citation.yaml rename to schema/notes/citation.yaml index 8006e43..85aedb8 100644 --- a/schema/yaml/citation.yaml +++ b/schema/notes/citation.yaml @@ -1,7 +1,8 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/citation?version=v1 - usageNotes: | - The Citation is dynamically assembled from other entry elements in this format: Principal-Investigator-list. Study-Title. Distributor-list, Version-Date. DOI. ICPSR 'union catalog' records – i.e., external resource to which ICPSR links as a courtesy – do not have citations generated. + $id: https://schemas.icpsr.umich.edu/schema/notes/citation?version=v1 + usageNotes: |+ + The Citation is dynamically assembled from other entry elements in this format: Principal-Investigator-list. Study-Title. Distributor-list, Version-Date. DOI. ICPSR 'union catalog' records (i.e., external resource to which ICPSR links as a courtesy) do not have citations generated. For additional information about how DOIs for citations are generated, see the Digital Object Identifier element usage notes. + diff --git a/schema/yaml/collection_date_time_frame.yaml b/schema/notes/collection_date_time_frame.yaml similarity index 84% rename from schema/yaml/collection_date_time_frame.yaml rename to schema/notes/collection_date_time_frame.yaml index b69021a..f7b8477 100644 --- a/schema/yaml/collection_date_time_frame.yaml +++ b/schema/notes/collection_date_time_frame.yaml @@ -1,7 +1,9 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/collection_date_time_frame?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/collection_date_time_frame?version=v1 + usageNotes: |+ The textual description ('time frame') is used to add context to the Collection Date when multiple time periods exist (e.g., to describe different study waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. + + diff --git a/schema/yaml/collection_mode.yaml b/schema/notes/collection_mode.yaml similarity index 98% rename from schema/yaml/collection_mode.yaml rename to schema/notes/collection_mode.yaml index 3abd996..ebf11c9 100644 --- a/schema/yaml/collection_mode.yaml +++ b/schema/notes/collection_mode.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/collection_mode?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/collection_mode?version=v1 controlledVocab: | Local ICPSR controlled vocabulary. See below for terms and definitions: diff --git a/schema/yaml/data_type.yaml b/schema/notes/data_type.yaml similarity index 96% rename from schema/yaml/data_type.yaml rename to schema/notes/data_type.yaml index 7fcfb27..de8fa0b 100644 --- a/schema/yaml/data_type.yaml +++ b/schema/notes/data_type.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/data_type?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/data_type?version=v1 controlledVocab: | Local ICPSR controlled vocabulary. See below for terms and definitions: diff --git a/schema/yaml/distributor.yaml b/schema/notes/distributor.yaml similarity index 77% rename from schema/yaml/distributor.yaml rename to schema/notes/distributor.yaml index 2ca7daf..e9f852d 100644 --- a/schema/yaml/distributor.yaml +++ b/schema/notes/distributor.yaml @@ -1,7 +1,9 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/distributor?version=v1 - icpsrGuidance: | - Most data collections list ICPSR as the distributor. As such, the full name and location of ICPSR are easily accessible in the metadata editor. + $id: https://schemas.icpsr.umich.edu/schema/notes/distributor?version=v1 + icpsrGuidance: |+ + Most data collections list ICPSR as the distributor. As such, the full name and location of ICPSR are easily accessible in the metadata editor. If a non-ICPSR distributor is necessary, please confirm the standards with the Metadata Librarian. Please note that external distributors are often appropriate for Union Catalog entries and metadata-only releases. + + diff --git a/schema/yaml/extent_of_processing.yaml b/schema/notes/extent_of_processing.yaml similarity index 97% rename from schema/yaml/extent_of_processing.yaml rename to schema/notes/extent_of_processing.yaml index 444b596..ef30e23 100644 --- a/schema/yaml/extent_of_processing.yaml +++ b/schema/notes/extent_of_processing.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/extent_of_processing?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/extent_of_processing?version=v1 controlledVocab: | Local ICPSR controlled vocabulary. See below for terms and definitions: diff --git a/schema/notes/external_source_ID.yaml b/schema/notes/external_source_ID.yaml new file mode 100644 index 0000000..c5c973d --- /dev/null +++ b/schema/notes/external_source_ID.yaml @@ -0,0 +1,10 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/schema/notes/external_source_ID?version=v1 + icpsrGuidance: |+ + This is an internal ICPSR element that is not publicly displayed. An External Source ID consists of: + + * an ICPSR-defined source organization code + * a colon + * a Depositor-supplied ID. + diff --git a/schema/yaml/funding_agency.yaml b/schema/notes/funding_agency.yaml similarity index 87% rename from schema/yaml/funding_agency.yaml rename to schema/notes/funding_agency.yaml index 42f0c6b..1e22172 100644 --- a/schema/yaml/funding_agency.yaml +++ b/schema/notes/funding_agency.yaml @@ -1,10 +1,11 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/funding_agency?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/funding_agency?version=v1 + usageNotes: |+ When entering the name of a funding agency, the following hierarchy of authority control sources should be used to make sure the name conforms to best practices within ICPSR and the broader academic community: 1. If the funding agency has sponsored archived data at ICPSR, use the name as it has been displayed previously within the ICPSR catalog. 2. If the funding agency is in the [ICPSR Organization Names Authority List](https://www.icpsr.umich.edu/web/ICPSR/thesaurus/10004), conform to the listed name form. 3. If the funding agency is not available in an ICPSR authority list, consult [VIAF](https://viaf.org). - 4. If the funding agency does not have a VIAF record, consult another authoritative source, such as the organization's website or Google Scholar. \ No newline at end of file + 4. If the funding agency does not have a VIAF record, consult another authoritative source, such as the organization's website or Google Scholar. + diff --git a/schema/yaml/funding_purpose.yaml b/schema/notes/funding_purpose.yaml similarity index 86% rename from schema/yaml/funding_purpose.yaml rename to schema/notes/funding_purpose.yaml index f329742..5cee239 100644 --- a/schema/yaml/funding_purpose.yaml +++ b/schema/notes/funding_purpose.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/funding_purpose?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/funding_purpose?version=v1 controlledVocab: | Local ICPSR controlled vocabulary. See below for terms and definitions: diff --git a/schema/yaml/geographic_coverage_area.yaml b/schema/notes/geographic_coverage_area.yaml similarity index 89% rename from schema/yaml/geographic_coverage_area.yaml rename to schema/notes/geographic_coverage_area.yaml index 957c433..585a29f 100644 --- a/schema/yaml/geographic_coverage_area.yaml +++ b/schema/notes/geographic_coverage_area.yaml @@ -1,7 +1,7 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/geographic_coverage_area?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/geographic_coverage_area?version=v1 + usageNotes: |+ Each geographic term's full hierarchy must be included; please note: * For a U.S. city, the state and country are listed alongside (e.g., 'Los Angeles, California, United States'). @@ -10,7 +10,7 @@ * County-level information is typically not indicated. If a U.S. county will be included, the state name and 'United States' must be listed as well. The [Getty Thesaurus of Geographic Names](http://www.getty.edu/research/tools/vocabularies/tgn/index.html) is referenced when introducing new geographic names. - icpsrGuidance: | + icpsrGuidance: |+ The metadata editor will automatically put this element's values in alphabetical order, regardless of hierarchy. - For United States-based data collections that include some or all U.S. island territories (e.g., American Samoa, Puerto Rico, Northern Mariana Islands, Virgin Islands of the United States, and Guam), list each of these territories separately in the Geographic Coverage Areas field. \ No newline at end of file + For United States-based data collections that include some or all U.S. island territories (e.g., American Samoa, Puerto Rico, Northern Mariana Islands, Virgin Islands of the United States, and Guam), list each of these territories separately in the Geographic Coverage Areas field. diff --git a/schema/yaml/pi_names.yaml b/schema/notes/pi_names.yaml similarity index 97% rename from schema/yaml/pi_names.yaml rename to schema/notes/pi_names.yaml index 5fb6e95..19b4de3 100644 --- a/schema/yaml/pi_names.yaml +++ b/schema/notes/pi_names.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/pi_names?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/pi_names?version=v1 usageNotes: |+ List individuals and organizations that are chiefly responsible for the study across its entire life cycle or made significant intellectual contributions to the research. A principal investigator (PI) may be a person or an organization; use the Person or Organization element as appropriate. If the PI is identified as a person, their affiliated organization (if applicable) should be included in the Organization element. diff --git a/schema/yaml/scale.yaml b/schema/notes/scale.yaml similarity index 89% rename from schema/yaml/scale.yaml rename to schema/notes/scale.yaml index f490890..91cb4ae 100644 --- a/schema/yaml/scale.yaml +++ b/schema/notes/scale.yaml @@ -1,5 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/scale?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/scale?version=v1 + usageNotes: |+ Include common scales that can be readily identified from the data, documentation, or other related materials. ICPSR curators are not expected to infer or research scales that are not explicitly indicated. The scales can be cited either as a list or described in full sentences. If the questionnaire used has a finite list of responses (e.g., 'Always, Sometimes, Rarely, Never' or Strongly Agree, Agree, Disagree, Strongly Disagree'), it is acceptable for this element to note 'A Likert-type scale was used,' or 'Several Likert-type scales were used.' However, it is not required to note Likart-type scales in situations where only such scales were used, given their ubiquity. + diff --git a/schema/yaml/smallest_geographic_unit.yaml b/schema/notes/smallest_geographic_unit.yaml similarity index 75% rename from schema/yaml/smallest_geographic_unit.yaml rename to schema/notes/smallest_geographic_unit.yaml index 099b3c3..a012764 100644 --- a/schema/yaml/smallest_geographic_unit.yaml +++ b/schema/notes/smallest_geographic_unit.yaml @@ -1,11 +1,14 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/smallest_geographic_unit?version=v1 - usageNotes: | - Geographic Unit is intended to represent specific, known geography -- e.g., county, census district, FIPS code, electoral district, and any other conveyor of specific geography that is represented by a variable. + $id: https://schemas.icpsr.umich.edu/schema/notes/smallest_geographic_unit?version=v1 + usageNotes: |+ + Geographic Unit is intended to represent specific, known geography – e.g., county, census district, FIPS code, electoral district, and any other conveyor of specific geography that is represented by a variable. If the data do not include a geographic variable by which the data can be analyzed, this element is not indicated. If all the cases are from a single state, but the cases are not subdivided geographically within that state, then 'state' is not indicated. This element is only meant to convey specific, known, geography. If there is a variable indicating which testing site a survey was taken at, but the locations of the testing sites were masked by the PI, this element is likely not indicated. - icpsrGuidance: | + + + icpsrGuidance: |+ The following is a non-exhaustive list of potential entries: census tract, city, congressional district, Core-Based Statistical Area (CBSA), country, county, Federal Court District, FIPS code, jurisdiction, neighborhood, school district, state, ZIP code. + diff --git a/schema/yaml/study_design.yaml b/schema/notes/study_design.yaml similarity index 83% rename from schema/yaml/study_design.yaml rename to schema/notes/study_design.yaml index a5bd239..59cdd8a 100644 --- a/schema/yaml/study_design.yaml +++ b/schema/notes/study_design.yaml @@ -1,7 +1,11 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/study_design?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/study_design?version=v1 + usageNotes: |+ The Study Design provides more detailed information than the Summary, including how surveys were prepared and administered, how interviews were conducted, or how the data were obtained and compiled, as well as information about deadlines and follow-ups to respondents. - icpsrGuidance: | + + + icpsrGuidance: |+ It is acceptable to summarize information contained in study documentation and point users to that study documentation for more details. If the Summary already contains text that would be appropriate in Study Design, it is acceptable to duplicate that text. + + diff --git a/schema/yaml/summary.yaml b/schema/notes/summary.yaml similarity index 93% rename from schema/yaml/summary.yaml rename to schema/notes/summary.yaml index 8200296..6336589 100644 --- a/schema/yaml/summary.yaml +++ b/schema/notes/summary.yaml @@ -1,9 +1,11 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/summary?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/summary?version=v1 + usageNotes: |+ The main goal of the Summary is to give the reader a clear sense of what the data collection is about, including substantive information about the different parts of the data collection not adequately conveyed by the Fileset names or found elsewhere in the metadata. A listing of major variables or categories of variables with a few examples is also important. It is also salient to indicate the unit of analysis for the data collection, i.e., who or what is being studied: individuals, housing units, courts, criminal acts, etc. Most often the unit of analysis is the individual; where it is not, it is particularly important to make this clear. The Summary is written in the third person and avoids attempting to address issues of how the data might be used, who might be interested in the data, or any evaluative comments about the worth or usefulness of the data collection. The Summary uses past tense when describing the process of collecting the data and present tense when necessary, such as when describing the data (e.g., 'The MIDUS Refresher collection is split into two datasets.'). Numerals are used instead of spelling them out; if a number is spelled out for emphasis, the number is attached in parentheses (e.g. 'Two thousand (2,000)'). + + diff --git a/schema/yaml/time_method.yaml b/schema/notes/time_method.yaml similarity index 97% rename from schema/yaml/time_method.yaml rename to schema/notes/time_method.yaml index 2cca6c1..7d222ed 100644 --- a/schema/yaml/time_method.yaml +++ b/schema/notes/time_method.yaml @@ -1,6 +1,6 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/time_method?version=v1 + $id: https://schemas.icpsr.umich.edu/schema/notes/time_method?version=v1 controlledVocab: | [DDI Controlled Vocabulary for Time Method](https://vocabularies.cessda.eu/vocabulary/TimeMethod). See below for terms and definitions: diff --git a/schema/yaml/time_period_date.yaml b/schema/notes/time_period_date.yaml similarity index 86% rename from schema/yaml/time_period_date.yaml rename to schema/notes/time_period_date.yaml index 64f500f..43aa9ad 100644 --- a/schema/yaml/time_period_date.yaml +++ b/schema/notes/time_period_date.yaml @@ -1,9 +1,11 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/time_period_date?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/time_period_date?version=v1 + usageNotes: |+ Time Periods focus on the dates the data are actually about, regardless of when the data were collected. Time Periods generally correspond to the dates that appear in the Title; days and months may be included in the Time Period even though they are not in the Title. Dates are formatted in accordance with ISO 8601 (YYYY, YYYY-MM, or YYYY-MM-DD). One hyphen separates the parts of a date; two hyphens separate two dates. Ranges may be expressed in years (YYYY--YYYY), months (YYYY-MM--YYYY-MM), or days (YYYY-MM-DD--YYYY-MM-DD). No spaces are permitted in date expressions. + + diff --git a/schema/yaml/time_period_time_frame.yaml b/schema/notes/time_period_time_frame.yaml similarity index 84% rename from schema/yaml/time_period_time_frame.yaml rename to schema/notes/time_period_time_frame.yaml index 920186c..13da076 100644 --- a/schema/yaml/time_period_time_frame.yaml +++ b/schema/notes/time_period_time_frame.yaml @@ -1,7 +1,9 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/time_period_time_frame?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/time_period_time_frame?version=v1 + usageNotes: |+ The textual description ('time frame') is used to add context to the Time Period when multiple time periods exist (e.g., to describe different waves, dataset names, or fiscal year designation) and/or when the date cannot be expressed exclusively through numbers, such as seasons or other units of time where the data producer did not clarify the exact dates they meant. The textual description should not simply restate the time period in words. For example, if the Time Period is 2020-01, the Time Frame should not be 'January 2020'. + + diff --git a/schema/notes/title.yaml b/schema/notes/title.yaml new file mode 100644 index 0000000..79eeb57 --- /dev/null +++ b/schema/notes/title.yaml @@ -0,0 +1,40 @@ +--- + $schema: https://json-schema.org/draft-07/schema# + $id: https://schemas.icpsr.umich.edu/schema/notes/title?version=v1 + usageNotes: |+ + The Title includes three essential parts: the title proper, the geography, and the time period. + + Title Proper: + + * The title proper is a descriptive string that captures what the data collection contains. + + * The title proper uses title case: all major words are capitalized, while minor words are lowercased. + + * For new studies, ICPSR starts with the title proper provided by the data depositor. Most title propers are straightforward about their contents, such as the 'American Community Survey' or the 'Census of Law Enforcement Training Academies.' Some title propers include a more branded description, such as 'Bridge of Faith: Aim4Peace Community-Based Violence Prevention Project or Contents' and 'Contexts of Cyberbullying: An Epidemiologic Study using Electronic Detection and Social Network Analysis.' + + * For updated studies, ICPSR uses the existing title in production, making changes as necessary to add new years or additional geographical locations. For studies that are part of an ICPSR series, titles remain consistent with the previous series studies. + + Geography: + + * All titles include the data collection's geography. If the geography is already included in the title proper, it is not repeated. + + * Cities are paired with state or province names that are spelled out (e.g., Portland, Oregon), unless the city names are unique or well-known. + + * Studies with more than four geographic locations typically are summarized using, for example, '5 countries,' '8 German cities,' '20 U.S. states' instead of listing all locations. In the latter case, 'U.S.' is used rather than 'United States' or 'American'. + + * Descriptors that do not have a distinct geographic area, such as 'communities' or 'regions', are not included in titles. + + * 'Global' may be appropriate for studies where the universe of participants is truly worldwide. Possible examples include online surveys that are not restricted by geography, or studies of organizations, such as NGOs. + + * Brackets are typically not indicated. They are indicated when a study has National, Federal, Congressional, or American in the title. Brackets can be indicated if a non-United States study has "National" in the title, or a similar word specific to that country. + + Time Period: + + * All titles include the data collection's time period, which reflects the time period that the data collection covers and should match the Time Period. For example, in the 'Uganda Elite Study, 1964-1968', it is assumed that the Ugandans were surveyed about events in 1964-1968, even if the actual data collection might not have taken place until later. + + * If the time period is already included in the title proper, it is not repeated. + + * For most studies, a single year or range of years is acceptable. Years are written as four digits, including when used in a range (e.g., '1999', '2001-2003', or '1999, 2010, 2015'). + + * Months are included only when part of ICPSR series that have multiple releases, which are otherwise identical, each year. In these cases, months are spelled out (e.g., 'September 2020' instead of '9/2020' or 'Sept. 2020'). + diff --git a/schema/yaml/version.yaml b/schema/notes/version.yaml similarity index 89% rename from schema/yaml/version.yaml rename to schema/notes/version.yaml index dc9f834..03787ca 100644 --- a/schema/yaml/version.yaml +++ b/schema/notes/version.yaml @@ -1,7 +1,7 @@ --- $schema: https://json-schema.org/draft-07/schema# - $id: https://schemas.icpsr.umich.edu/schema/yaml/version?version=v1 - usageNotes: | + $id: https://schemas.icpsr.umich.edu/schema/notes/version?version=v1 + usageNotes: |+ Version numbers are integers without leading zeros. Versioning begins when a data collection is first archived. Each subsequent update of the data collection increments the version number by 1. The version number is incremented when modifying or adding: * Data files, including additions of datasets or supplemental data files, additional masking, increasing curation level, or resupplied datasets @@ -9,3 +9,4 @@ * SDA (Survey Documentation and Analysis) files Metadata-only updates to the data collection do not increment the version number. Changes to the version number require a textual summary to be added to Changes to Collection. +