From 7c062ad3d80854d21028ab64e0b07d9537ad37cc Mon Sep 17 00:00:00 2001 From: Brian Beck Date: Mon, 28 Nov 2016 19:14:43 -0800 Subject: [PATCH] Add more argument descriptions, add new rendered type docs, move schema.md to doc dir --- README.md | 5 +- schema.md => doc/schema.md | 76 +- doc/types.md | 3850 ++++++++++++++++++++++++++++++++++++ package.json | 10 +- schema.json | 30 +- scripts/render-types.js | 145 ++ src/types/helpers.js | 15 +- src/types/life-span.js | 15 +- 8 files changed, 4112 insertions(+), 34 deletions(-) rename schema.md => doc/schema.md (96%) create mode 100644 doc/types.md create mode 100644 scripts/render-types.js diff --git a/README.md b/README.md index 40897e0..5f9ed8e 100644 --- a/README.md +++ b/README.md @@ -283,7 +283,7 @@ agree, it’s ugly. ## Schema -See the [GraphQL schema][schema]. +See the [GraphQL schema][schema] or the [rendered documentation][types]. [demo]: https://graphbrainz.herokuapp.com/ [Express]: http://expressjs.com/ @@ -294,4 +294,5 @@ See the [GraphQL schema][schema]. [debug]: https://www.npmjs.com/package/debug [GraphiQL]: https://github.com/graphql/graphiql [Relay]: https://facebook.github.io/relay/ -[schema]: schema.md +[schema]: doc/schema.md +[types]: doc/types.md diff --git a/schema.md b/doc/schema.md similarity index 96% rename from schema.md rename to doc/schema.md index 34a9820..2c211af 100644 --- a/schema.md +++ b/doc/schema.md @@ -72,7 +72,16 @@ type Area implements Node, Entity { places(after: String, first: Int): PlaceConnection # A list of releases linked to this entity. - releases(after: String, first: Int, type: [ReleaseGroupType], status: [ReleaseStatus]): ReleaseConnection + releases( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + + # Filter by one or more release statuses. + status: [ReleaseStatus] + ): ReleaseConnection # Relationships between this entity and other entitites. relationships: Relationships @@ -173,10 +182,25 @@ type Artist implements Node, Entity { recordings(after: String, first: Int): RecordingConnection # A list of releases linked to this entity. - releases(after: String, first: Int, type: [ReleaseGroupType], status: [ReleaseStatus]): ReleaseConnection + releases( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + + # Filter by one or more release statuses. + status: [ReleaseStatus] + ): ReleaseConnection # A list of release groups linked to this entity. - releaseGroups(after: String, first: Int, type: [ReleaseGroupType]): ReleaseGroupConnection + releaseGroups( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + ): ReleaseGroupConnection # A list of works linked to this entity. works(after: String, first: Int): WorkConnection @@ -616,7 +640,16 @@ type Label implements Node, Entity { typeID: MBID # A list of releases linked to this entity. - releases(after: String, first: Int, type: [ReleaseGroupType], status: [ReleaseStatus]): ReleaseConnection + releases( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + + # Filter by one or more release statuses. + status: [ReleaseStatus] + ): ReleaseConnection # Relationships between this entity and other entitites. relationships: Relationships @@ -654,8 +687,13 @@ type LabelEdge { # Fields indicating the begin and end date of an entity’s # lifetime, including whether it has ended (even if the date is unknown). type LifeSpan { + # The start date of the entity’s life span. begin: Date + + # The end date of the entity’s life span. end: Date + + # Whether or not the entity’s life span has ended. ended: Boolean } @@ -899,7 +937,16 @@ type Recording implements Node, Entity { artists(after: String, first: Int): ArtistConnection # A list of releases linked to this entity. - releases(after: String, first: Int, type: [ReleaseGroupType], status: [ReleaseStatus]): ReleaseConnection + releases( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + + # Filter by one or more release statuses. + status: [ReleaseStatus] + ): ReleaseConnection # Relationships between this entity and other entitites. relationships: Relationships @@ -1296,7 +1343,13 @@ type Release implements Node, Entity { recordings(after: String, first: Int): RecordingConnection # A list of release groups linked to this entity. - releaseGroups(after: String, first: Int, type: [ReleaseGroupType]): ReleaseGroupConnection + releaseGroups( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + ): ReleaseGroupConnection # Relationships between this entity and other entitites. relationships: Relationships @@ -1391,7 +1444,16 @@ type ReleaseGroup implements Node, Entity { artists(after: String, first: Int): ArtistConnection # A list of releases linked to this entity. - releases(after: String, first: Int, type: [ReleaseGroupType], status: [ReleaseStatus]): ReleaseConnection + releases( + after: String + first: Int + + # Filter by one or more release group types. + type: [ReleaseGroupType] + + # Filter by one or more release statuses. + status: [ReleaseStatus] + ): ReleaseConnection # Relationships between this entity and other entitites. relationships: Relationships diff --git a/doc/types.md b/doc/types.md new file mode 100644 index 0000000..8e1d81e --- /dev/null +++ b/doc/types.md @@ -0,0 +1,3850 @@ +# Schema Types + +You may also be interested in the [schema in GraphQL syntax](schema.md). + +
**Table of Contents**

+ +## Query +The query root, from which multiple types of MusicBrainz +requests can be made. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Node](#fixme)Fetches an object given its ID
id[ID](#fixme)!The ID of an object
**lookup**[LookupQuery](#fixme)Perform a lookup of a MusicBrainz entity by its MBID.
**browse**[BrowseQuery](#fixme)Browse all MusicBrainz entities directly linked to another entity.
**search**[SearchQuery](#fixme)Search for MusicBrainz entities using Lucene query syntax.
+ +## Objects + +### Alias + +[Aliases](https://musicbrainz.org/doc/Aliases) are variant names +that are mostly used as search help: if a search matches an entity’s alias, the +entity will be given as a result – even if the actual name wouldn’t be. They are +available for artists, labels, and works. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**name**[String](#fixme)The aliased name of the entity.
**sortName**[String](#fixme)The string to use for the purpose of ordering by name (for +example, by moving articles like ‘the’ to the end or a person’s last name to +the front).
**locale**[String](#fixme)The locale (language and/or country) in which the alias is +used.
**primary**[Boolean](#fixme)Whether this is the main alias for the entity in the +specified locale (this could mean the most recent or the most common).
**type**[String](#fixme)The type or purpose of the alias – whether it is a variant, +search hint, etc.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
+ +### Area + +[Areas](https://musicbrainz.org/doc/Area) are geographic regions +or settlements (countries, cities, or the like). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**sortName**[String](#fixme)The string to use for the purpose of ordering by name (for +example, by moving articles like ‘the’ to the end or a person’s last name to +the front).
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**isoCodes**[[String](#fixme)]ISO 3166 codes are +the codes assigned by ISO to countries and subdivisions.
**artists**[ArtistConnection](#fixme)A list of artists linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**events**[EventConnection](#fixme)A list of events linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**labels**[LabelConnection](#fixme)A list of labels linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**places**[PlaceConnection](#fixme)A list of places linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**releases**[ReleaseConnection](#fixme)A list of releases linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
status[[ReleaseStatus](#fixme)]Filter by one or more release statuses.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### AreaConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[AreaEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### AreaEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Area](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Artist + +An [artist](https://musicbrainz.org/doc/Artist) is generally a +musician, group of musicians, or other music professional (like a producer or +engineer). Occasionally, it can also be a non-musical person (like a +photographer, an illustrator, or a poet whose writings are set to music), or +even a fictional character. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**sortName**[String](#fixme)The string to use for the purpose of ordering by name (for +example, by moving articles like ‘the’ to the end or a person’s last name to +the front).
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**country**[String](#fixme)The country with which an artist is primarily identified. It +is often, but not always, its birth/formation country.
**area**[Area](#fixme)The area with which an artist is primarily identified. It +is often, but not always, its birth/formation country.
**beginArea**[Area](#fixme)The area in which an artist began their career (or where +were born, if the artist is a person).
**endArea**[Area](#fixme)The area in which an artist ended their career (or where +they died, if the artist is a person).
**lifeSpan**[LifeSpan](#fixme)The begin and end dates of the entity’s existence. Its exact +meaning depends on the type of entity.
**gender**[String](#fixme)Whether a person or character identifies as male, female, or +neither. Groups do not have genders.
**genderID**[MBID](#fixme)The MBID associated with the value of the gender +field.
**type**[String](#fixme)Whether an artist is a person, a group, or something else.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**recordings**[RecordingConnection](#fixme)A list of recordings linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**releases**[ReleaseConnection](#fixme)A list of releases linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
status[[ReleaseStatus](#fixme)]Filter by one or more release statuses.
**releaseGroups**[ReleaseGroupConnection](#fixme)A list of release groups linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
**works**[WorkConnection](#fixme)A list of works linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### ArtistConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[ArtistEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### ArtistCredit + +[Artist credits](https://musicbrainz.org/doc/Artist_Credits) +indicate who is the main credited artist (or artists) for releases, release +groups, tracks and recordings, and how they are credited. They consist of +artists, with (optionally) their names as credited in the specific release, +track, etc., and join phrases between them. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**artist**[Artist](#fixme)The entity representing the artist referenced in the +credits.
**name**[String](#fixme)The name of the artist as credited in the specific release, +track, etc.
**joinPhrase**[String](#fixme)Join phrases might include words and/or punctuation to +separate artist names as they appear on the release, track, etc.
+ +### ArtistEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Artist](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### BrowseQuery + +A query for all MusicBrainz entities directly linked to another +entity. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**areas**[AreaConnection](#fixme)Browse area entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
**artists**[ArtistConnection](#fixme)Browse artist entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
area[MBID](#fixme)The MBID of an area to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
recording[MBID](#fixme)The MBID of a recording to which the entity is linked.
release[MBID](#fixme)The MBID of a release to which the entity is linked.
releaseGroup[MBID](#fixme)The MBID of a release group to which the entity is linked.
work[MBID](#fixme)The MBID of a work to which the artist is linked.
**events**[EventConnection](#fixme)Browse event entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
area[MBID](#fixme)The MBID of an area to which the entity is linked.
artist[MBID](#fixme)The MBID of an artist to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
place[MBID](#fixme)The MBID of a place to which the event is linked.
**labels**[LabelConnection](#fixme)Browse label entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
area[MBID](#fixme)The MBID of an area to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
release[MBID](#fixme)The MBID of a release to which the entity is linked.
**places**[PlaceConnection](#fixme)Browse place entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
area[MBID](#fixme)The MBID of an area to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
**recordings**[RecordingConnection](#fixme)Browse recording entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
artist[MBID](#fixme)The MBID of an artist to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
release[MBID](#fixme)The MBID of a release to which the entity is linked.
**releases**[ReleaseConnection](#fixme)Browse release entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
area[MBID](#fixme)The MBID of an area to which the entity is linked.
artist[MBID](#fixme)The MBID of an artist to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
label[MBID](#fixme)The MBID of a label to which the release is linked.
track[MBID](#fixme)The MBID of a track that is included in the release.
trackArtist[MBID](#fixme)The MBID of an artist that appears on a track in the +release, but is not included in the credits for the release itself.
recording[MBID](#fixme)The MBID of a recording to which the entity is linked.
releaseGroup[MBID](#fixme)The MBID of a release group to which the entity is linked.
**releaseGroups**[ReleaseGroupConnection](#fixme)Browse release group entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
artist[MBID](#fixme)The MBID of an artist to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
release[MBID](#fixme)The MBID of a release to which the entity is linked.
**works**[WorkConnection](#fixme)Browse work entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
artist[MBID](#fixme)The MBID of an artist to which the entity is linked.
collection[MBID](#fixme)The MBID of a collection in which the entity is found.
**urls**[URLConnection](#fixme)Browse URL entities linked to the given arguments.
after[String](#fixme)
first[Int](#fixme)
resource[URLString](#fixme)The web address for which to browse URL entities.
+ +### Coordinates + +Geographic coordinates described with latitude and longitude. + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**latitude**[Degrees](#fixme)The north–south position of a point on the Earth’s surface.
**longitude**[Degrees](#fixme)The east–west position of a point on the Earth’s surface.
+ +### Event + +An [event](https://musicbrainz.org/doc/Event) refers to an +organised event which people can attend, and is relevant to MusicBrainz. +Generally this means live performances, like concerts and festivals. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**lifeSpan**[LifeSpan](#fixme)The begin and end dates of the entity’s existence. Its exact +meaning depends on the type of entity.
**time**[Time](#fixme)The start time of the event.
**cancelled**[Boolean](#fixme)Whether or not the event took place.
**setlist**[String](#fixme)A list of songs performed, optionally including links to +artists and works. See the setlist documentation +for syntax and examples.
**type**[String](#fixme)What kind of event the event is, e.g. concert, festival, etc.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### EventConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[EventEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### EventEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Event](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Instrument + +[Instruments](https://musicbrainz.org/doc/Instrument) are +devices created or adapted to make musical sounds. Instruments are primarily +used in relationships between two other entities. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**description**[String](#fixme)A brief description of the main characteristics of the +instrument.
**type**[String](#fixme)The type categorises the instrument by the way the sound is +created, similar to the Hornbostel-Sachs +classification.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### InstrumentConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[InstrumentEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### InstrumentEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Instrument](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Label + +[Labels](https://musicbrainz.org/doc/Label) represent mostly +(but not only) imprints. To a lesser extent, a label entity may be created to +represent a record company. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**sortName**[String](#fixme)The string to use for the purpose of ordering by name (for +example, by moving articles like ‘the’ to the end or a person’s last name to +the front).
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**country**[String](#fixme)The country of origin for the label.
**area**[Area](#fixme)The area in which the label is based.
**lifeSpan**[LifeSpan](#fixme)The begin and end dates of the entity’s existence. Its exact +meaning depends on the type of entity.
**labelCode**[Int](#fixme)The “LC” code +of the label.
**ipis**[[IPI](#fixme)]List of IPI (interested party information) codes for the +label.
**type**[String](#fixme)A type describing the main activity of the label, e.g. +imprint, production, distributor, rights society, etc.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**releases**[ReleaseConnection](#fixme)A list of releases linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
status[[ReleaseStatus](#fixme)]Filter by one or more release statuses.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### LabelConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[LabelEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### LabelEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Label](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### LifeSpan + +Fields indicating the begin and end date of an entity’s +lifetime, including whether it has ended (even if the date is unknown). + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**begin**[Date](#fixme)The start date of the entity’s life span.
**end**[Date](#fixme)The end date of the entity’s life span.
**ended**[Boolean](#fixme)Whether or not the entity’s life span has ended.
+ +### LookupQuery + +A lookup of an individual MusicBrainz entity by its MBID. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**area**[Area](#fixme)Look up a specific area by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**artist**[Artist](#fixme)Look up a specific artist by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**event**[Event](#fixme)Look up a specific event by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**instrument**[Instrument](#fixme)Look up a specific instrument by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**label**[Label](#fixme)Look up a specific label by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**place**[Place](#fixme)Look up a specific place by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**recording**[Recording](#fixme)Look up a specific recording by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**release**[Release](#fixme)Look up a specific release by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**releaseGroup**[ReleaseGroup](#fixme)Look up a specific release group by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**series**[Series](#fixme)Look up a specific series by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**url**[URL](#fixme)Look up a specific URL by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
**work**[Work](#fixme)Look up a specific work by its MBID.
mbid[MBID](#fixme)!The MBID of the entity.
+ +### PageInfo + +Information about pagination in a connection. + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**hasNextPage**[Boolean](#fixme)!When paginating forwards, are there more items?
**hasPreviousPage**[Boolean](#fixme)!When paginating backwards, are there more items?
**startCursor**[String](#fixme)When paginating backwards, the cursor to continue.
**endCursor**[String](#fixme)When paginating forwards, the cursor to continue.
+ +### Place + +A [place](https://musicbrainz.org/doc/Place) is a venue, studio +or other place where music is performed, recorded, engineered, etc. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**address**[String](#fixme)The address describes the location of the place using the +standard addressing format for the country it is located in.
**area**[Area](#fixme)The area entity representing the area, such as the city, in +which the place is located.
**coordinates**[Coordinates](#fixme)The geographic coordinates of the place.
**lifeSpan**[LifeSpan](#fixme)The begin and end dates of the entity’s existence. Its exact +meaning depends on the type of entity.
**type**[String](#fixme)The type categorises the place based on its primary +function.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**events**[EventConnection](#fixme)A list of events linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### PlaceConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[PlaceEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### PlaceEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Place](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Recording + +A [recording](https://musicbrainz.org/doc/Recording) is an +entity in MusicBrainz which can be linked to tracks on releases. Each track must +always be associated with a single recording, but a recording can be linked to +any number of tracks. + +A recording represents distinct audio that has been used to produce at least one +released track through copying or mastering. A recording itself is never +produced solely through copying or mastering. + +Generally, the audio represented by a recording corresponds to the audio at a +stage in the production process before any final mastering but after any editing +or mixing. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**title**[String](#fixme)The official title of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**artistCredit**[[ArtistCredit](#fixme)]The main credited artist(s).
**length**[Int](#fixme)An approximation to the length of the recording, calculated +from the lengths of the tracks using it.
**video**[Boolean](#fixme)Whether this is a video recording.
**artists**[ArtistConnection](#fixme)A list of artists linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**releases**[ReleaseConnection](#fixme)A list of releases linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
status[[ReleaseStatus](#fixme)]Filter by one or more release statuses.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### RecordingConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[RecordingEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### RecordingEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Recording](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Relationship + +[Relationships](https://musicbrainz.org/doc/Relationships) are a +way to represent all the different ways in which entities are connected to each +other and to URLs outside MusicBrainz. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**target**[Entity](#fixme)!The target entity.
**direction**[String](#fixme)!The direction of the relationship.
**targetType**[String](#fixme)!The type of entity on the receiving end of the relationship.
**sourceCredit**[String](#fixme)How the source entity was actually credited, if different +from its main (performance) name.
**targetCredit**[String](#fixme)How the target entity was actually credited, if different +from its main (performance) name.
**begin**[Date](#fixme)The date on which the relationship became applicable.
**end**[Date](#fixme)The date on which the relationship became no longer applicable.
**ended**[Boolean](#fixme)Whether the relationship still applies.
**attributes**[[String](#fixme)]Attributes which modify the relationship. There is a list +of all attributes, but the +attributes which are available, and how they should be used, depends on the +relationship type.
**type**[String](#fixme)The type of relationship.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
+ +### RelationshipConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[RelationshipEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### RelationshipEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Relationship](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Relationships + +Lists of entity relationships for each entity type. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**areas**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**artists**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**events**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**instruments**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**labels**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**places**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**recordings**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**releases**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**releaseGroups**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**series**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**urls**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
**works**[RelationshipConnection](#fixme)A list of relationships between these two entity types.
after[String](#fixme)
first[Int](#fixme)
before[String](#fixme)
last[Int](#fixme)
direction[String](#fixme)Filter by the relationship direction.
type[String](#fixme)Filter by the relationship type.
typeID[MBID](#fixme)The MBID associated with the value of the type +field.
+ +### Release + +A [release](https://musicbrainz.org/doc/Release) represents the +unique release (i.e. issuing) of a product on a specific date with specific +release information such as the country, label, barcode, packaging, etc. If you +walk into a store and purchase an album or single, they’re each represented in +MusicBrainz as one release. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**title**[String](#fixme)The official title of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**artistCredit**[[ArtistCredit](#fixme)]The main credited artist(s).
**releaseEvents**[[ReleaseEvent](#fixme)]The release events for this release.
**date**[Date](#fixme)The release date +is the date in which a release was made available through some sort of +distribution mechanism.
**country**[String](#fixme)The country in which the release was issued.
**barcode**[String](#fixme)The barcode, if the +release has one. The most common types found on releases are 12-digit +UPCs and 13-digit +EANs.
**status**[ReleaseStatus](#fixme)The status describes how “official” a release is.
**statusID**[MBID](#fixme)The MBID associated with the value of the status +field.
**packaging**[String](#fixme)The physical packaging that accompanies the release. See +the list of packaging for more +information.
**packagingID**[MBID](#fixme)The MBID associated with the value of the packaging +field.
**quality**[String](#fixme)Data quality indicates how good the data for a release is. +It is not a mark of how good or bad the music itself is – for that, use +ratings.
**artists**[ArtistConnection](#fixme)A list of artists linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**labels**[LabelConnection](#fixme)A list of labels linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**recordings**[RecordingConnection](#fixme)A list of recordings linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**releaseGroups**[ReleaseGroupConnection](#fixme)A list of release groups linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### ReleaseConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[ReleaseEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### ReleaseEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Release](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### ReleaseEvent + +Date on which a release was issued in a country/region with a +particular label, catalog number, barcode, and what release format was used. + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**area**[Area](#fixme)
**date**[Date](#fixme)
+ +### ReleaseGroup + +A [release group](https://musicbrainz.org/doc/Release_Group) is +used to group several different releases into a single logical entity. Every +release belongs to one, and only one release group. + +Both release groups and releases are “albums” in a general sense, but with an +important difference: a release is something you can buy as media such as a CD +or a vinyl record, while a release group embraces the overall concept of an +album – it doesn’t matter how many CDs or editions/versions it had. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**title**[String](#fixme)The official title of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**artistCredit**[[ArtistCredit](#fixme)]The main credited artist(s).
**firstReleaseDate**[Date](#fixme)The date of the earliest release in the group.
**primaryType**[ReleaseGroupType](#fixme)The type +of a release group describes what kind of releases the release group represents, +e.g. album, single, soundtrack, compilation, etc. A release group can have a +“main” type and an unspecified number of additional types.
**primaryTypeID**[MBID](#fixme)The MBID associated with the value of the primaryType +field.
**secondaryTypes**[[ReleaseGroupType](#fixme)]Additional types +that apply to this release group.
**secondaryTypeIDs**[[MBID](#fixme)]The MBIDs associated with the values of the secondaryTypes +field.
**artists**[ArtistConnection](#fixme)A list of artists linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**releases**[ReleaseConnection](#fixme)A list of releases linked to this entity.
after[String](#fixme)
first[Int](#fixme)
type[[ReleaseGroupType](#fixme)]Filter by one or more release group types.
status[[ReleaseStatus](#fixme)]Filter by one or more release statuses.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### ReleaseGroupConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[ReleaseGroupEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### ReleaseGroupEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[ReleaseGroup](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### SearchQuery + +A search for MusicBrainz entities using Lucene query syntax. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**areas**[AreaConnection](#fixme)Search for area entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**artists**[ArtistConnection](#fixme)Search for artist entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**events**[EventConnection](#fixme)Search for event entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**instruments**[InstrumentConnection](#fixme)Search for instrument entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**labels**[LabelConnection](#fixme)Search for label entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**places**[PlaceConnection](#fixme)Search for place entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**recordings**[RecordingConnection](#fixme)Search for recording entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**releases**[ReleaseConnection](#fixme)Search for release entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**releaseGroups**[ReleaseGroupConnection](#fixme)Search for release group entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**series**[SeriesConnection](#fixme)Search for series entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
**works**[WorkConnection](#fixme)Search for work entities matching the given query.
query[String](#fixme)!The query terms, in Lucene search syntax. See examples +and search fields.
after[String](#fixme)
first[Int](#fixme)
+ +### Series + +A [series](https://musicbrainz.org/doc/Series) is a sequence of +separate release groups, releases, recordings, works or events with a common +theme. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**name**[String](#fixme)The official name of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**type**[String](#fixme)The type primarily describes what type of entity the series +contains.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### SeriesConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[SeriesEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### SeriesEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Series](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Tag + +[Tags](https://musicbrainz.org/tags) are a way to mark entities +with extra information – for example, the genres that apply to an artist, +release, or recording. + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**name**[String](#fixme)!The tag label.
**count**[Int](#fixme)How many times this tag has been applied to the entity.
+ +### TagConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[TagEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### TagEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Tag](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### URL + +A [URL](https://musicbrainz.org/doc/URL) pointing to a resource +external to MusicBrainz, i.e. an official homepage, a site where music can be +acquired, an entry in another database, etc. + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**resource**[URLString](#fixme)!The actual URL string.
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
+ +### URLConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[URLEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### URLEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[URL](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +### Work + +A [work](https://musicbrainz.org/doc/Work) is a distinct +intellectual or artistic creation, which can be expressed in the form of one or +more audio recordings. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**id**[ID](#fixme)!The ID of an object
**mbid**[MBID](#fixme)!The MBID of the entity.
**title**[String](#fixme)The official title of the entity.
**disambiguation**[String](#fixme)A comment used to help distinguish identically named entitites.
**aliases**[[Alias](#fixme)]Aliases are used to store +alternate names or misspellings.
**iswcs**[[String](#fixme)]A list of ISWCs assigned +to the work by copyright collecting agencies.
**language**[String](#fixme)The language in which the work was originally written.
**type**[String](#fixme)The type of work.
**typeID**[MBID](#fixme)The MBID associated with the value of the type +field.
**artists**[ArtistConnection](#fixme)A list of artists linked to this entity.
after[String](#fixme)
first[Int](#fixme)
**relationships**[Relationships](#fixme)Relationships between this entity and other entitites.
**tags**[TagConnection](#fixme)A list of tags linked to this entity.
after[String](#fixme)
first[Int](#fixme)
+ +### WorkConnection + +A connection to a list of items. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**pageInfo**[PageInfo](#fixme)!Information to aid in pagination.
**edges**[[WorkEdge](#fixme)]A list of edges.
**totalCount**[Int](#fixme)A count of the total number of items in this connection, +ignoring pagination.
+ +### WorkEdge + +An edge in a connection. + + + + + + + + + + + + + + + + + + + +
Field / ArgumentTypeDescription
**node**[Work](#fixme)The item at the end of the edge
**cursor**[String](#fixme)!A cursor for use in pagination
**score**[Int](#fixme)The relevancy score (0–100) assigned by the search engine, if +these results were found through a search.
+ +## Enums + +### ReleaseGroupType + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
**ALBUM**An album, perhaps better defined as a “Long Play” (LP) +release, generally consists of previously unreleased material (unless this type +is combined with secondary types which change that, such as “Compilation”). This +includes album re-issues, with or without bonus tracks.
**SINGLE**A single typically has one main song and possibly a handful +of additional tracks or remixes of the main track. A single is usually named +after its main song.
**EP**An EP is a so-called “Extended Play” release and often +contains the letters EP in the title. Generally an EP will be shorter than a +full length release (an LP or “Long Play”) and the tracks are usually exclusive +to the EP, in other words the tracks don’t come from a previously issued +release. EP is fairly difficult to define; usually it should only be assumed +that a release is an EP if the artist defines it as such.
**OTHER**Any release that does not fit any of the other categories.
**BROADCAST**An episodic release that was originally broadcast via radio, +television, or the Internet, including podcasts.
**COMPILATION**A compilation is a collection of previously released tracks +by one or more artists.
**SOUNDTRACK**A soundtrack is the musical score to a movie, TV series, +stage show, computer game, etc.
**SPOKENWORD**A non-music spoken word release.
**INTERVIEW**An interview release contains an interview, generally with +an artist.
**AUDIOBOOK**An audiobook is a book read by a narrator without music.
**LIVE**A release that was recorded live.
**REMIX**A release that was (re)mixed from previously released +material.
**DJMIX**A DJ-mix is a sequence of several recordings played one +after the other, each one modified so that they blend together into a continuous +flow of music. A DJ mix release requires that the recordings be modified in some +manner, and the DJ who does this modification is usually (although not always) +credited in a fairly prominent way.
**MIXTAPE**Promotional in nature (but not necessarily free), mixtapes +and street albums are often released by artists to promote new artists, or +upcoming studio albums by prominent artists. They are also sometimes used to +keep fans’ attention between studio releases and are most common in rap & hip +hop genres. They are often not sanctioned by the artist’s label, may lack proper +sample or song clearances and vary widely in production and recording quality. +While mixtapes are generally DJ-mixed, they are distinct from commercial DJ +mixes (which are usually deemed compilations) and are defined by having a +significant proportion of new material, including original production or +original vocals over top of other artists’ instrumentals. They are distinct from +demos in that they are designed for release directly to the public and fans, not +to labels.
**DEMO**A release that was recorded for limited circulation or +reference use rather than for general public release.
**NAT**A non-album track (special case).
+ +### ReleaseStatus + + + + + + + + + + + + + + + + + + + + +
ValueDescription
**OFFICIAL**Any release officially sanctioned by the artist and/or their +record company. (Most releases will fit into this category.)
**PROMOTION**A giveaway release or a release intended to promote an +upcoming official release, e.g. prerelease albums or releases included with a +magazine.
**BOOTLEG**An unofficial/underground release that was not sanctioned by +the artist and/or the record company.
**PSEUDORELEASE**A pseudo-release is a duplicate release for +translation/transliteration purposes.
+ +## Scalars + +### Boolean + +The `Boolean` scalar type represents `true` or `false`. + +### Date + +Year, month (optional), and day (optional) in YYYY-MM-DD format. + +### Degrees + +Decimal degrees, used for latitude and longitude. + +### ID + +The `ID` scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as `"4"`) or integer (such as `4`) input value will be accepted as an ID. + +### IPI + +An [IPI](https://musicbrainz.org/doc/IPI) (interested party +information) code is an identifying number assigned by the CISAC database for +musical rights management. + +### Int + +The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1. + +### MBID + +The MBID scalar represents MusicBrainz identifiers, which are +36-character UUIDs. + +### String + +The `String` scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text. + +### Time + +A time of day, in 24-hour hh:mm notation. + +### URLString + +A web address. + + +## Interfaces + +### Entity + +An entity in the MusicBrainz schema. + +### Node + +An object with an ID + diff --git a/package.json b/package.json index 18053db..a8f86a3 100644 --- a/package.json +++ b/package.json @@ -17,7 +17,10 @@ }, "scripts": { "build": "npm run build:lib && npm run update-schema && npm run build:docs", - "build:docs": "doctoc --title \"## Contents\" README.md", + "build:docs": "npm run build:docs:readme && npm run build:docs:schema && npm run build:docs:types", + "build:docs:readme": "doctoc --title \"## Contents\" README.md", + "build:docs:schema": "printf '# GraphQL Schema\\n\\n%s' \"$(npm run -s print-schema:md)\" > doc/schema.md", + "build:docs:types": "babel-node scripts/render-types.js > doc/types.md", "build:lib": "babel --out-dir lib src", "clean": "npm run clean:lib", "clean:lib": "rm -rf lib", @@ -31,9 +34,7 @@ "start": "node lib/index.js", "start:dev": "nodemon --exec babel-node src/index.js", "test": "mocha --compilers js:babel-register", - "update-schema": "npm run update-schema:json && npm run update-schema:md", - "update-schema:json": "npm run -s print-schema:json > schema.json", - "update-schema:md": "printf '# GraphQL Schema\\n\\n%s' \"$(npm run -s print-schema:md)\" > schema.md" + "update-schema": "npm run -s print-schema:json > schema.json" }, "keywords": [ "musicbrainz", @@ -80,6 +81,7 @@ "babel-register": "^6.18.0", "chai": "^3.5.0", "doctoc": "^1.2.0", + "marked": "^0.3.6", "mocha": "^3.2.0", "nodemon": "^1.11.0", "snazzy": "^5.0.0", diff --git a/schema.json b/schema.json index d9435fd..f496e3f 100644 --- a/schema.json +++ b/schema.json @@ -787,7 +787,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -801,7 +801,7 @@ }, { "name": "status", - "description": null, + "description": "Filter by one or more release statuses.", "type": { "kind": "LIST", "name": null, @@ -1514,7 +1514,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -1528,7 +1528,7 @@ }, { "name": "status", - "description": null, + "description": "Filter by one or more release statuses.", "type": { "kind": "LIST", "name": null, @@ -1575,7 +1575,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -1698,7 +1698,7 @@ "fields": [ { "name": "begin", - "description": null, + "description": "The start date of the entity’s life span.", "args": [], "type": { "kind": "SCALAR", @@ -1710,7 +1710,7 @@ }, { "name": "end", - "description": null, + "description": "The end date of the entity’s life span.", "args": [], "type": { "kind": "SCALAR", @@ -1722,7 +1722,7 @@ }, { "name": "ended", - "description": null, + "description": "Whether or not the entity’s life span has ended.", "args": [], "type": { "kind": "SCALAR", @@ -2030,7 +2030,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -2044,7 +2044,7 @@ }, { "name": "status", - "description": null, + "description": "Filter by one or more release statuses.", "type": { "kind": "LIST", "name": null, @@ -2752,7 +2752,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -3179,7 +3179,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -3193,7 +3193,7 @@ }, { "name": "status", - "description": null, + "description": "Filter by one or more release statuses.", "type": { "kind": "LIST", "name": null, @@ -5029,7 +5029,7 @@ }, { "name": "type", - "description": null, + "description": "Filter by one or more release group types.", "type": { "kind": "LIST", "name": null, @@ -5043,7 +5043,7 @@ }, { "name": "status", - "description": null, + "description": "Filter by one or more release statuses.", "type": { "kind": "LIST", "name": null, diff --git a/scripts/render-types.js b/scripts/render-types.js new file mode 100644 index 0000000..e92fc59 --- /dev/null +++ b/scripts/render-types.js @@ -0,0 +1,145 @@ +import marked from 'marked' +const schema = require('../schema.json').data.__schema + +marked.setOptions({ + breaks: false +}) + +function markdown (markup) { + return marked(markup || '') + .replace(/<\/p>\s*

/g, '

') + .replace(/<\/?p>/g, '') + .trim() +} + +function sortBy (arr, property) { + arr.sort((a, b) => { + const aValue = a[property] + const bValue = b[property] + if (aValue > bValue) return 1 + if (bValue > aValue) return -1 + return 0 + }) +} + +function renderType (type) { + if (type.kind === 'NON_NULL') { + return renderType(type.ofType) + '!' + } + if (type.kind === 'LIST') { + return `[${renderType(type.ofType)}]` + } + return `[${type.name}](#fixme)` +} + +function renderObject (type, { skipTitle = false } = {}) { + if (!skipTitle) { + console.log(`\n### ${type.name}\n`) + } + if (type.description) { + console.log(`${type.description}\n`) + } + console.log('') + console.log(' ') + console.log('') + type.fields.forEach(field => { + console.log(' ') + console.log(` `) + console.log(` `) + console.log(` `) + console.log(' ') + if (field.args.length) { + field.args.forEach((arg, i) => { + console.log(' ') + console.log(` `) + console.log(` `) + console.log(` `) + console.log(' ') + }) + } + }) + console.log('
Field / ArgumentTypeDescription
**${field.name}**${renderType(field.type)}${markdown(field.description)}
${arg.name}${renderType(arg.type)}${markdown(arg.description)}
') +} + +const types = schema.types.filter(type => !type.name.startsWith('__')) +const query = types.filter(type => type.name === schema.queryType.name)[0] +const objects = types.filter(type => type.kind === 'OBJECT' && type !== query) +const enums = types.filter(type => type.kind === 'ENUM').sort() +const scalars = types.filter(type => type.kind === 'SCALAR').sort() +const interfaces = types.filter(type => type.kind === 'INTERFACE').sort() + +sortBy(objects, 'name') +sortBy(enums, 'name') +sortBy(scalars, 'name') +sortBy(interfaces, 'name') + +console.log('# Schema Types\n') + +console.log('You may also be interested in the [schema in GraphQL syntax](schema.md).\n') + +console.log('

**Table of Contents**

') + +console.log(`\n## Query ${query.name === 'Query' ? '' : '(' + query.name + ')'}`) +renderObject(query, { skipTitle: true }) + +console.log('\n## Objects') +objects.forEach(type => renderObject(type)) + +console.log('\n## Enums') + +enums.forEach(type => { + console.log(`\n### ${type.name}\n`) + if (type.description) { + console.log(`${type.description}\n`) + } + console.log('') + console.log(' ') + console.log('') + type.enumValues.forEach(value => { + console.log(' ') + console.log(` `) + console.log(` `) + console.log(' ') + }) + console.log('
ValueDescription
**${value.name}**${markdown(value.description)}
') +}) + +console.log('\n## Scalars\n') + +scalars.forEach(type => { + console.log(`### ${type.name}\n`) + if (type.description) { + console.log(`${type.description}\n`) + } +}) + +console.log('\n## Interfaces\n') + +interfaces.forEach(type => { + console.log(`### ${type.name}\n`) + if (type.description) { + console.log(`${type.description}\n`) + } +}) diff --git a/src/types/helpers.js b/src/types/helpers.js index 5d0b9e1..7bc2cd1 100644 --- a/src/types/helpers.js +++ b/src/types/helpers.js @@ -208,13 +208,22 @@ export const places = linkedQuery(PlaceConnection) export const recordings = linkedQuery(RecordingConnection) export const releases = linkedQuery(ReleaseConnection, { args: { - type: { type: new GraphQLList(ReleaseGroupType) }, - status: { type: new GraphQLList(ReleaseStatus) } + type: { + type: new GraphQLList(ReleaseGroupType), + description: 'Filter by one or more release group types.' + }, + status: { + type: new GraphQLList(ReleaseStatus), + description: 'Filter by one or more release statuses.' + } } }) export const releaseGroups = linkedQuery(ReleaseGroupConnection, { args: { - type: { type: new GraphQLList(ReleaseGroupType) } + type: { + type: new GraphQLList(ReleaseGroupType), + description: 'Filter by one or more release group types.' + } } }) export const tags = linkedQuery(TagConnection, { diff --git a/src/types/life-span.js b/src/types/life-span.js index a6a05c3..9633a55 100644 --- a/src/types/life-span.js +++ b/src/types/life-span.js @@ -6,8 +6,17 @@ export default new GraphQLObjectType({ description: `Fields indicating the begin and end date of an entity’s lifetime, including whether it has ended (even if the date is unknown).`, fields: () => ({ - begin: { type: DateType }, - end: { type: DateType }, - ended: { type: GraphQLBoolean } + begin: { + type: DateType, + description: 'The start date of the entity’s life span.' + }, + end: { + type: DateType, + description: 'The end date of the entity’s life span.' + }, + ended: { + type: GraphQLBoolean, + description: 'Whether or not the entity’s life span has ended.' + } }) })