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.

    • Comic issues (or just comics) are the physical or digital products that end-users read. (The Marvel Comics API returns comic issues, collections, graphic novels and digital comics as part of the overall comics endpoint and entity type.)
    • Comics belong to a series, which is a (usually) sequentially number list of comics with the same title and volume. Marvel uses the year of original publication for a series as the volume number.
    • Comics can also be a part of an event, which is a big, universe-changing storyline. A comic's appearance in an event is often independent of its membership in a series.
    • Comics are made up of stories, which are indivisible components of comics. Most comics have two stories – a cover and an interior story - but many, such as anthology comics and collections, will have more. Stories may be re-published in several comics, but the comic in which they originally appeared will always be present as a data point.
    • Creators are the people and entities that make comics. They are assigned to the specific comic stories on which they worked, but we bubble up those assignments to the issues, series and events in which the stories appear as a convenience.
    • Characters are people and organizations which appear in comics. They are also assigned to stories initially and bubbled up to issues, series and events.

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:

attribute type description
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:

attribute type description
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:

attribute type description
available int The number of total available resources in this list
returned int The number of resources returned in this resource list (up to 20).
collectionURI string The 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.

attribute type description
path string The directory path of to the image.
extension string The file extension for the image.

Core Entity Representations

Characters:
attribute type description
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:
attribute type description
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).
variantDescription string If 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:
attribute type description
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:
attribute type description
id int The unique ID of the event resource.
title stding The title of the event.
description stding A description of the event.
resourceURI stding The canonical URL identifier for this resource.
urls Array[Url] A set of public web site URLs for the event.
modified Date The date the resource was most recently modified.
start Date The date of publication of the first issue in this event.
end Date The date of publication of the last issue in this event.
thumbnail Image The representative image for this event.
comics ResourceList A resource list containing the comics in this event.
stories ResourceList A resource list containing the stories in this event.
series ResourceList A resource list containing the series in this event.
characters ResourceList A resource list containing the characters which appear in this event.
creators ResourceList A resource list containing creators whose work appears in this event.
next EventSummary A summary representation of the event which follows this event.
previous EventSummary A summary representation of the event which preceded this event.
Series:
attribute type description
id int The unique ID of the series resource.
title string The canonical title of the series.
description string A description of the series.
resourceURI string The canonical URL identifier for this resource.
urls Array[Url] A set of public web site URLs for the resource.
startYear int The first year of publication for the series.
endYear int The last year of publication for the series (conventionally, 2099 for ongoing series).
rating string The age-appropriateness rating for the series.
modified Date The date the resource was most recently modified.
thumbnail Image The representative image for this series.
comics ResourceList A resource list containing comics in this series.
stories ResourceList A resource list containing stories which occur in comics in this series.
events ResourceList A resource list containing events which take place in comics in this series.
characters ResourceList A resource list containing characters which appear in comics in this series.
creators ResourceList A resource list of creators whose work appears in comics in this series.
next SeriesSummary A summary representation of the series which follows this series.
previous SeriesSummary A summary representation of the series which preceded this series.
Stories:
attribute type description
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.