Artifact Metadata Best Practices and Considerations

Artifacts are imported using the Artifact Importer function. The importer collects and stores metadata about artifacts that are housed elsewhere on the Internet.

The hub uses metadata to facilitate searches and to display useful artifact information to researchers.Thoughtful choices for metadata will help other researchers find and reuse your artifacts. 

It is important to pre-plan your artifact metadata before publishing the artifact. Once published, the artifact can no longer be edited.  We recommend iterating over the artifact, changing and saving metadata, and then doing a thorough review before publishing. If you are submitting several related artifacts, we recommend iteratively creating and saving all of the artifacts and doing a review across all of them pior to publishing any in the set.  This will give you time to normalize language, keywords, and relationships across the set. 

Note: We plan a future version of the hub that allows versioning of artifacts, much like Wikipedia pages are versioned. We do not have any ETA for when this feature will be released.

Meta fields and recommendations and considerations are:

Title

The Title field should be short and descriptive of what the artifact is. For example, "TLS Fingerprint Datasets" or "OpenIntel Active DNS Measurements: Open Access ccTLDS". This field is displayed in the artifact search results. An artifact may have only one title.

User search strings are matched against the title field. Matches are displayed in the search results. 

Description

The detailed description field is displayed in the artifact search results. It should be short and suscinctly convey the information needed to enable a hub user to quickly assess if the artifact is of possible interest. An artifact may have only one detailed description.

Note that if there is a README.md file, it will be displayed directly following the description field when viewing the artifact.

User search strings are matched against the description field. Matches are displayed in the search results. 

URL

This is the primary URL of the artifact. An artifact may have only one primary URL. For publications and presentations, we recommend using the official DOI URL, if one exists. If there is none, we recommend using the page where the publication or presentation is posted.

For software and datasets, we recommend using the main repository URL or if there is no repository, the URL for the web page where it is posted. 

Use only fully qualified URLs (e.g., "https://data.openintel.nl/data/alexa1m/").

Artifact type

Artifact types are limited to supported system types: software, datasets, publications, presentations, and other. An artifact may have only one type. More information about artifact types may be found here.

Artifact type is a searchable field under "advanced" search. 

Roles

Roles are persons associated with the artifact. At present, the only roles presently displayed are authors. An object owner is a separate role which is not displayed at this time. An artifact may have one owner and multiple authors.

Each author associated with an artifact should be added as a separate entry. To add an author, click on the + sign under Roles, and enter the author's organization, name and email address. A list of known organizations is available. Search and choose from that list (this will keep organization names consistent in the database, which will better enable searching across organizations in the future.) If the needed organization is not found, you can add it by typing the organization's name into the organization field. Click "Add" to save the author information. Repeat the process for each author you wish to add.

At present, roles are not searchable. We plan to add this feature in a future release.

Keywords

Keywords are relevant terms used to facilitate searches. This is a good place to add alternate terms for the same object. 

An artifact may have multiple keywords. Each keyword should be added individually. To add a keyword, click on the + sign under Keywords, type the keyword (can include blanks) into the blue box, and press Enter. Click the + sign to add another keyword. To delete a keyword, click the X on the right hand side of the keyword.

User search strings are matched against the specified keywords. Matches are displayed in the search results. 

Languages

The languages field is used to specify the programming languages used for software (e.g., Python, Go). It can also be used to specify the written language of a paper. 

An artifact may have multiple languages. Each language should be added individually. To add a language, click on the + sign under Languages, type the language name into the purple box, and press Enter. Click the + sign to add another language. To delete a language, click the X on the right hand side of the language.

This field is not searchable.

Related artifacts

Related artifacts allows users to specify other artifacts that are related to this artifact. More information about artifact relationships may be found here.

Related artifacts are clickable, meaning a user can walk from one artifact to a related artifact.

Badges

The badges field is for artifact award badges (e.g., ACM Artifacts Evaluated as Reusable).

An artifact may have multiple badges. Each badge should be added individually. To add a badge, click on the + sign under Badges, choose a badge from the supported list in the gray box, and press Enter. Click the + sign to add another badge. To delete a badge, click the X on the right hand side of the badge.

The badge field is not searchable.

License

This field contains the primary license for the artifact. Values are limited to the known licenses. An artifact may have only one primary license. If other licenses also apply, these should be specified in the documentation.

To add a license, click in the gray box under Licenses and choose from the list of known open source licenses. If the needed license does not exist, please use the feedback form to request that the needed license be added.

This field is not searchable.

Files

File URL metadata allows the artifact owner to create direct links to important files that are part of the artifact. For example, a dataset artifact might have a direct pointer to a tar.gzip file and a readme.txt file.  Use only fully qualified URLs (e.g., "https://securepki.org/data/README.txt").

An artifact may have multiple associated files. To add a file URL, click on the + sign under Files and type the full URL into the provided white box. Press enter when finished.  Click the + sign to add another file URL. To delete a file URL, click the X on the right hand side of the URL.

File fields are clickable, meaning a user to jump directly to the linked files.