Artifact files

This page documents the schema of artifact files for Ace Archive. See acearchive/artifacts on GitHub for more information.

If you’re not particularly interested in the technical details of this site and you’re not familiar with YAML and git, you might want to check out our contributor documentation instead.

URL slugs

Every artifact in the repository has a URL like:

https://acearchive.lgbt/artifact/orlando-the-asexual-manifesto

When you add a new artifact, you need to choose a URL slug for it, which is that last part of the path.

A URL slug should always be lowercase and use hyphens to separate words, and it will generally follow the format author-title. If the author has a first and last name (i.e. isn’t a handle or username), you can just use the last name. If the title of the work is long, you can use a shortened version of it. If there is no obvious author associated with the work, you can just use the title.

If the combination of the author and the title of the work is ambiguous, (such as a forum thread where the title of the thread might just be “asexuality”), then you can provide additional context like context-author-title. For an AVEN forum thread by “coolasexualperson” called “romance”, the URL slug might be aven-forums-coolasexualperson-romance.

Schema

This is the schema of artifact files. Also take a look at the best practices section for more information on how to fill out these fields.

version integer
Sometimes the format of artifact files changes. This is the version number for the artifact file format. This will be set to the current version when you open a pull request, so you can leave it alone.
title string
This is the title of the artifact. If the artifact represents a creative work (a book, essay, blog post, etc.), this should be the title of that work. If the artifact encompasses multiple works or doesn’t have an obvious title, it can be a short description instead. You should always quote or italicize the titles of works; you can add italics in an artifact title using markdown *Title of Work* syntax.
description string
This is a short, one sentence description of the artifact that should provide context and explain its significance to the queer community (i.e. why it’s in the archive). This description should complete the sentence “This artifact is…” You should always quote or italicize the titles of works; you can add italics in an artifact description using markdown *Title of Work* syntax.
longDescription string optional
If you want to provide more context than you can fit in the short description, you can optionally provide a longer description that will appear in the page for the artifact. This should also complete the sentence “This artifact is…”
files list of dictionaries optional
The list files to include in the artifact.
files.name string
A label for the file. If the artifact consists of multiple creative works, this should generally include the title of the work so people can disambiguate them. If the artifact consists of a single work, it can be something short like “Paper,” “Transcript,” “Citation,” etc.
files.mediaType string optional
The file type of the file. This should be formatted as a MIME type like application/pdf or image/png. If you need help figuring out the MIME type of a file, you can use mimetype.io to look it up. If the file is a format that doesn’t have a well-known MIME type, you can omit this.
files.filename string optional
A file name to be used when downloading the file. This should use hyphens instead of spaces and should always include an appropriate file extension. If the file is actually a directory containing multiple files, you can omit this.
files.cid string
This is the CID (content identifier) of the file. This also accepts a dweb.link URL. You need to upload the file to Web3.Storage to get its CID. For more information, see the docs.
links list of dictionaries optional
A list of links to web sites to include in the artifact.
links.name string
A label for the link. If the artifact consists of multiple creative works, this should generally include the title of the work so people can disambiguate them. If the artifact consists of a single work, it can be something short like “Paper,” “Transcript,” “Citation,” etc.
links.url string
The https:// URL that the link points to.
people list of strings optional
A list of (usually 1-4) people closely associated with the artifact, such as the author of a book, the subject of a photo, the original poster of a forum thread, the person who coined a new term, etc. This is helpful for linking together different artifacts which are associated with the same people. This can be omitted if the people associated with the artifact aren’t clear or there were many different people involved.
identities list of strings optional
A list of queer identities associated with the artifact. For example, if this is a blog post about aromanticism, then “aromantic” should be included in the list of identities. The identity should be in adjective form, meaning it can complete the sentence, “Artifacts about _ people”. This can be omitted if the identities associated with the work aren’t clear (e.g. it’s about queer identities as a whole).
fromYear integer
The year the creative work associated with the artifact was published (or written, posted, etc.). If the artifact encompasses multiple works that were published in different years, this should be the year the first work was published.
toYear integer optional
If the artifact encompasses multiple creative works that were published in different years, this should be the year the last work was published. If the works associated with the artifact were only published in one year, this should be omitted.
decades list of integers
The list of decades in which a creative work associated with the artifact was published. If a work was published in 1980 and another work was published in 2009, this should include 1980 and 2000.
aliases list of strings optional
If the URL slug of an artifact must change for any reason, you must specify all of its previous URL slugs here so that the old links can redirect to the new one. For new artifacts, you should omit this.

Edit this page on GitHub