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.