code.json

Once you have completed the domain review, you will need to add a code.json metadata file to your repository. This file provides metadata about your project, and is one of the required files for the administrative review. This file must be written in the JSON format, and must contain certain required fields.

We recommend authors use the following code.json template to prepare their metadata. The remainder of this page discusses each field in detail. Note that the TEAM_NAME field in the template will be ghsc/lhp for most LHP projects. Also, the RELEASE_VERSION field refers to the release tag.

Note

The template file is written or a first release. Please see the Multiple Releases section if this is not the first release of your project.

name

A short human-readable name for the project. This should match the title of the project on Gitlab, which is not necessarily the same as the slug.

organization

Do not change this field. It must always be exactly U.S. Geological Survey.

description

A short description or tagline for the project. This shouldn’t be more than 1 or 2 lines long. (Longer descriptions can go in the README).

version

This should be the tag for the release. It should not contain a v prefix or other identifier.

status

This must be one of the following values:

  • Ideation

  • Development

  • Alpha

  • Beta

  • Release Candidate

  • Production

  • Archival

Most official releases should be given the Production status, and not Release Candidate.

permissions.usageType

Do not change this field. You must always use an open source license.

permissions.license.name

You should change this to the name of the license you selected for your project.

permissions.license.url

Update the license URL template to point to the eventual location of the LICENSE.md file of the release. Note that this URL won’t actually work until you finalize the release.

homepageURL

A link to the homepage for the project. This page must be publicly accessible. This can be a link to the official repository, or to another homepage elsewhere on the usgs.gov website.

downloadURL

A download link for the source code of the release. Note that this URL won’t actually work until you finalize the release.

disclaimerURL

A link to the DISCLAIMER.md file for the release. Note that this URL won’t actually work until you finalize the release.

repositoryURL

A link to the official upstream repository for the project. Note that the URL must end with a .git extension.

vcs

The version control system used to manage the software. This will almost always be git, so you should not edit this field.

laborHours

An integer estimating the number of hours of labor required to produce the software.

tags

An array of tags relevant to the project. Note that if the project uses artificial intelligence or machine learning in any way, then this array MUST include the tag usg-artificial-intelligence. Note that the usg here is correct, do not change it to usgs.

languages

An array of the programming languages used in the project.

date.metadataLastUpdated

An ISO datestamp of when the code.json file was last updated. You should update this field whenever you edit the code.json file.

Multiple Releases

If this is not the first release of your project, then you will need to update the existing code.json file, rather than creating a new one. Specifically, you should add a new release object to the array. The square brackets [] at the beginning and end of the code.json file indicate that the file holds an array of release objects. Each release is enclosed within curly brackets {}. To update the code.json file, you should append a new release object (the part of the template in curly brackets) to the top of the array. Use a comma to separate release objects. The final code.json will look something like the following:

[
    {
        "name": "REPOSITORY_NAME",
        ...
        "version": 2.0.0,
        ...
    },
    {
        "name": "REPOSITORY_NAME",
        ...
        "version": 1.2.0,
        ...
    },
    {
        "name": "REPOSITORY_NAME",
        ...
        "version": 1.1.0,
        ...
    },
    {
        "name": "REPOSITORY_NAME",
        ...
        "version": 1.0.0,
        ...
    },
]

Warning

Do not remove any of the previous releases from the code.json file.

Note

The release objects should be ordered from newest to oldest.