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.
Every artifact in the repository has a URL like:
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
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.
- 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.
- 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.
- 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.
- 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…”
fileslist of dictionaries optional
- The list files to include in the artifact.
- 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.
- The file type of the file. This should be formatted as a MIME type like
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.
- 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.
- This is the CID (content identifier) of the file. This also accepts a
dweb.linkURL. You need to upload the file to Web3.Storage to get its CID. For more information, see the docs.
linkslist of dictionaries optional
- A list of links to web sites to include in the artifact.
- 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.
https://URL that the link points to.
peoplelist 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.
identitieslist 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).
- 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.
- 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.
decadeslist 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.
aliaseslist 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.