Entity Types and Representations

In addition to telling epic stories of misunderstood teenagers swinging between the skyscrapers of Manhattan, comics have a robust and complex data model and consist of several different entity types. Before we get into the specifics of the API results we'll explain what these entities are and how they relate to each other.

(If you are interested in comics data structures and making comics more accessible generally, join Marvel in participating in the proposal process for schema.org and Biblex extensions for web schemas.)

Entity Representations

Entities returned by the API will have two representations: a full view and a summary view. The full view is returned by requests to a resource endpoint, and summaries are returned when a resource is referenced by a full resource. For example, a call to the comics endpoint http://gateway.marvel.com/v1/public/comics returns full views of comics and summaries of other entities such as creators which created the comic, characters which appear in it and the series in which the comic belongs.

We will explain the full representations of entities more in-depth below - they will vary from entity type to entity type.

Summary views will always contain a resourceURI, which points to the full representation of the referenced entity, and a name, for convenience. Some summary representations will additionally have a field describing its type or the relationship between the returned entity and the referenced entity.

You can expect that any result returned by an endpoint to have a full set of fields, but some fields may have empty values. For example, a string attribute may return an empty string or null, but the field will always be present in the returned representation.

Full schemas for each endpoint are also available in the interactive documentation.

Common structures

While each entity type returned by an endpoint has a distinct structure, many will have components which have a common structure.

URLs

URLs are references to web pages or deep links into applications. (When present in a resultset, it is preferred that you use these to link back to Marvel.) Many resources will have more than one representation on the web so URLs are generally presented as an array of URL resources. URLs are modeled as follows:

attributetypedescription
type string A text identifier for the URL.
url string A full URL (including scheme, domain, and path).

Text Objects

Text objects are bits of descriptive text which are attached to an entity. They have the following properties:

attributetypedescription
type string The string description of the text object (e.g. solicit text, preview text, etc.).
language string A language code denoting which language the text object is written in.
text string The text of the text object.

Resource URIs

Resource URIs are references to the representation of a resource within the API. Every resource and resource summary will have a resource URI attribute.

Resource Lists

Resource lists are collections of summary views within the context of another entity type. For example, the list of creators attached to a comic would be presented as resource list inside the full representation of that comic. Resource lists have the following format:

attributetypedescription
available intThe number of total available resources in this list
returned intThe number of resources returned in this resource list (up to 20).
collectionURI stringThe path to the list of full view representations of the items in this resource list.
items Array[entity summary representations] A list of summary views of the items in this resource list.

Requests to the collectionURI will return full representations of the entities in the resource list. For example, the uri http://gateway.marvel.com/v1/public/creators/32 will return a representation of a particular creator. That creator representation will have an issues attribute which is a resource list of issues that he or she worked on. A call to the resource list's collection URI http://gateway.marvel.com/v1/public/creators/32/comics will return a set of full representations of comics, filtered by the creator with id of 32.

Images:

Images are represented as a partial path and an extension. See the guide to images for information about how to construct full paths to image files.

attributetypedescription
path string The directory path of to the image.
extension string The file extension for the image.

Core Entity Representations

Characters:

attributetypedescription
id int The unique ID of the character resource.
name string The name of the character.
description string A short bio or description of the character.
modified Date The date the resource was most recently modified.
resourceURI string The canonical URL identifier for this resource.
urls Array[Url] A set of public web site URLs for the resource.
thumbnail Image The representative image for this character.
comics ResourceList A resource list containing comics which feature this character.
stories ResourceList A resource list of stories in which this character appears.
events ResourceList A resource list of events in which this character appears.
series ResourceList A resource list of series in which this character appears.

Comics:

attributetypedescription
id int The unique ID of the comic resource.
digitalId int The ID of the digital comic representation of this comic. Will be 0 if the comic is not available digitally.
title string The canonical title of the comic.
issueNumber int The number of the issue in the series (will generally be 0 for collection formats).
variantDescriptionstringIf the issue is a variant (e.g. an alternate cover, second printing, or director's cut), a text description of the variant.
description string The preferred description of the comic.
modified Date The date the resource was most recently modified.
isbn string The ISBN for the comic (generally only populated for collection formats).
upc string The UPC barcode number for the comic (generally only populated for periodical formats).
diamondCode string The Diamond code for the comic.
ean string The EAN barcode for the comic.
issn string The ISSN barcode for the comic.
format string The publication format of the comic e.g. comic, hardcover, trade paperback.
pageCount int The number of story pages in the comic.
textObjects Array[TextObject] A set of descriptive text blurbs for the comic.
resourceURI string The canonical URL identifier for this resource.
urls Array[Url] A set of public web site URLs for the resource.
series SeriesSummary A summary representation of the series to which this comic belongs.
variants Array[ComicSummary] A list of variant issues for this comic (includes the "original" issue if the current issue is a variant).
collections Array[ComicSummary] A list of collections which include this comic (will generally be empty if the comic's format is a collection).
collectedIssues Array[ComicSummary] A list of issues collected in this comic (will generally be empty for periodical formats such as "comic" or "magazine").
dates Array[ComicDate] A list of key dates for this comic.
prices Array[ComicPrice] A list of prices for this comic.
thumbnail Image The representative image for this comic.
images Array[Image] A list of promotional images associated with this comic.
creators ResourceList A resource list containing the creators associated with this comic.
characters ResourceList A resource list containing the characters which appear in this comic.
stories ResourceList A resource list containing the stories which appear in this comic.
events ResourceList A resource list containing the events in which this comic appears.

Creators:

attributetypedescription
id int The unique ID of the creator resource.
firstName string The first name of the creator.
middleName string The middle name of the creator.
lastName string The last name of the creator.
suffix string The suffix or honorific for the creator.
fullName string The full name of the creator (a space-separated concatenation of the above four fields).
modified Date The date the resource was most recently modified.
resourceURI string The canonical URL identifier for this resource.
urls Array[Url] A set of public web site URLs for the resource.
thumbnail Image The representative image for this creator.
series ResourceList A resource list containing the series which feature work by this creator.
stories ResourceList A resource list containing the stories which feature work by this creator.
comics ResourceList A resource list containing the comics which feature work by this creator.
events ResourceList A resource list containing the events which feature work by this creator.

Events:

attributetypedescription
id intThe unique ID of the event resource.
title stdingThe title of the event.
description stdingA description of the event.
resourceURI stdingThe canonical URL identifier for this resource.
urls Array[Url]A set of public web site URLs for the event.
modified DateThe date the resource was most recently modified.
start DateThe date of publication of the first issue in this event.
end DateThe date of publication of the last issue in this event.
thumbnail ImageThe representative image for this event.
comics ResourceListA resource list containing the comics in this event.
stories ResourceListA resource list containing the stories in this event.
series ResourceListA resource list containing the series in this event.
characters ResourceListA resource list containing the characters which appear in this event.
creators ResourceListA resource list containing creators whose work appears in this event.
next EventSummaryA summary representation of the event which follows this event.
previous EventSummaryA summary representation of the event which preceded this event.

Series:

attributetypedescription
id intThe unique ID of the series resource.
title stringThe canonical title of the series.
description stringA description of the series.
resourceURI stringThe canonical URL identifier for this resource.
urls Array[Url]A set of public web site URLs for the resource.
startYear intThe first year of publication for the series.
endYear intThe last year of publication for the series (conventionally, 2099 for ongoing series).
rating stringThe age-appropriateness rating for the series.
modified DateThe date the resource was most recently modified.
thumbnail ImageThe representative image for this series.
comics ResourceListA resource list containing comics in this series.
stories ResourceListA resource list containing stories which occur in comics in this series.
events ResourceListA resource list containing events which take place in comics in this series.
characters ResourceListA resource list containing characters which appear in comics in this series.
creators ResourceListA resource list of creators whose work appears in comics in this series.
next SeriesSummaryA summary representation of the series which follows this series.
previous SeriesSummaryA summary representation of the series which preceded this series.

Stories:

attributetypedescription
id int The unique ID of the story resource.
title string The story title.
description string A short description of the story.
resourceURI string The canonical URL identifier for this resource.
type string The story type e.g. interior story, cover, text story.
modified Date The date the resource was most recently modified.
thumbnail Image The representative image for this story.
comics ComicList A resource list containing comics in which this story takes place.
series SeriesList A resource list containing series in which this story appears.
events EventList A resource list of the events in which this story appears.
characters CharacterList A resource list of characters which appear in this story.
creators CreatorList A resource list of creators who worked on this story.
originalissue ComicSummary A summary representation of the issue in which this story was originally published.