Alexa Entities Reference

An Alexa entity represents a real-world person, place, or thing. Built-in slot types that support entity resolution disambiguate user utterances into specific, known entities.

The Alexa knowledge graph contains data about entities. Each entity is a node linked to other entities in the knowledge graph. Use the Linked Data API in your skill to retrieve information related to the entities.

Built-in slot types that support entity resolution

Built-in slot types that support entity resolution disambiguate user utterances into specific, known entities in the Alexa knowledge graph. Each entity has a unique ID in the form of an internationalized URI (IRI). You can use the IRI to call the Linked Data API to get information about the entity. For details about retrieving an IRI, see Retrieve the IRI from the skill request

The following table shows the list of built-in slot types that support entity resolution. For each slot type, the table indicates how you can use the entity IRIs. Note the following meaning of the columns:

  • Built-in slot type – The name of a built-in slot type that supports entity resolution.
  • Possible entity classes – If slot type values resolve to entities with data in the knowledge graph, this column lists the possible entity classes for those entities. The entity class determines the set of properties available for the entity when you retrieve the entity with the Linked Data API. See the linked topic for each entity for the set of properties available for each entity.

    An entity can have multiple classes. For example, a value for the AMAZON.Author slot type might resolve to an entity that has both entertainment:Author and Person properties.

Built-in slot type Possible entity classes

AMAZON.Actor

entertainment:Actor

Person

AMAZON.Animal

AnimalType

AMAZON.Book

Book

BookVersion

AMAZON.City

City

AMAZON.Country

Country

AMAZON.Director

entertainment:Director

Person

AMAZON.Movie

Movie

MovieVersion

AMAZON.Musician

entertainment:Musician

Person

AMAZON.MusicAlbum

MusicAlbum

AMAZON.MusicGroup

MusicGroup

AMAZON.MusicRecording

AudioTrack

AMAZON.Person

Person

AMAZON.TVSeries

TvSeries

Built-in slot type Possible entity classes

AMAZON.Actor

entertainment:Actor

Person

AMAZON.Animal

AnimalType

AMAZON.Author

entertainment:Author

Person

AMAZON.Book

Book

BookVersion

AMAZON.City

City

AMAZON.Country

Country

AMAZON.Director

entertainment:Director

Person

AMAZON.Movie

Movie

MovieVersion

AMAZON.Musician

entertainment:Musician

Person

AMAZON.MusicAlbum

MusicAlbum

AMAZON.MusicGroup

MusicGroup

AMAZON.MusicRecording

AudioTrack

AMAZON.Person

Person

AMAZON.TVSeries

TvSeries

Data structures and namespaces

Alexa Entities use a Resource Description Framework (RDF) data model. The data model defines the entity classes and properties that Alexa supports. Every type and every property has an internationalized URI (IRI) registered under the https://schema.amazonalexa.com/ domain. For example, the AMAZON.Person slot type has entities from the https://schema.amazonalexa.com/core/1.0/Person class.

To reduce the length of these identifiers and make them easier to use in code, the data uses a common set of prefixes. A prefix is a shorthand replacement for a URL domain and path. For example, the prefix core: represents the URL https://schema.amazonalexa.com/core/1.0/. Therefore, the following identifiers reference the same class:

  • core:Person
  • https://schema.amazonalexa.com/core/1.0/Person

Entity classes and properties use namespaces to disambiguate similar names and to indicate the namespace (the place in the ontology) where a given property or class is located. For example, the entertainment: prefix is a shorthand for https://schema.amazonalexa.com/entertainment/1.0/. This format is used for properties like entertainment:director and classes like entertainment:Author.

The core: namespace is the default. In the JSON-LD response, any property or type that doesn't have a prefix is in the core namespace. This default simplifies syntax for the most common classes and properties.

Some properties located in the core: namespace might have a prefix, which looks like a namespace. This prefix disambiguates the semantics of that property. This prefix most often corresponds to the class that sits at the left of that property, and it would look something like the following: https://schema.amazonalexa.com/core/1.0/CreativeWork/producer, or creativeWork:, for short.

Alexa Entities and JSON-LD syntax

An Alexa entity is a node within the Alexa knowledge graph, potentially linked to other nodes. Properties provide links to the other nodes. For example, a Person entity might have a birthplace property. This property returns a link to a Place entity, which you can use to retrieve information about that specific place.

Entities are represented in JSON-LD syntax, which is a standard format intended for linked data. In your skill code, work with a JSON-LD response the same way you work with any JSON file. You don't need special tools or libraries, but understanding some basics of how JSON-LD presents linked data might be helpful.

A JSON-LD document returned by the Linked Data API contains different types of properties. Properties named with an "at" sign (@) are JSON-LD keywords. For example, @id always refers to an ID represented as an IRI.

Object properties

An object property is a property that represents a link to an entity in the knowledge graph. For example, the birthplace property for a Person entity returns a link to the entity representing the person's birthplace. You can use the link to call the Linked Data API again to retrieve more details about the linked entity.

An object property returns a JSON object with the following properties:

  • @id – The ID of the entity, provided as an IRI. Use the IRI to retrieve the entity with the Linked Data API.
  • @type (required) – An array of classes for the linked entity. An entity can have multiple classes, such as Person and entertainment:Author. An object property always includes @type.
  • name – A data property containing an array of names for the entity.

Every object property has a @type. The @id and name properties are optional and might not be included for a particular object.

{
  "birthplace": {
    "@id": "https://ld.amazonalexa.com/entities/v1/DEPQSUzTa1nCPkZJPJVWoC",
    "@type": [
      "City"
    ],
    "name": [
      {
        "@language": "en",
        "@value": "Albuquerque, New Mexico"
      }
    ]
  }
}

Data properties

A data property represents a literal value and doesn't have an IRI. For example, the birthdate property for a Person entity returns a literal date value.

A data property returns a JSON object with the following properties:

  • @value – The literal value. For example, the string "1982-01-28" for a date. XML Schema
  • @type – The data type for interpreting the literal value. For example, asd:DateTime. Not included for localized string values (rdf:PlainLiteral).
  • @language: Included for a localized string (rdf:PlainLiteral) values. A local code indicating the language for the @value. For example, en-US. Use the Accept-Language header in the Linked Data API call to specify the locale returned.

For a list of possible data types, see Data types.

The following example shows an asd:DateTime data property:

{
  "birthdate": {
    "@type": "asd:DateTime",
    "@value": "1964-01-12"
  }
}

The following example shows an rdf:PlainLiteral data type for US English:

{
  "name": [
    {
      "@language": "en-us",
      "@value": "Jeff Bezos"
    }
  ]
}

When does a property return a single object or an array?

The characteristics of a property determine whether the property returns a single object or an array of values.

  • A functional property can have only one value at a time.
  • A permanent property has a value that can't change.
  • A transient property has a value that can change over time.

When a property is both functional and permanent, the property returns a JSON object that represents the single value. All other properties return an array of JSON objects. This means that a property that's both functional and transient returns an array with a single value.

These rules apply to both object properties and data properties.

Examples:

  • Functional and permanent – A Movie has one countryOfOrigin, and this value doesn't change over time. This property returns a single object.

      {
        "countryOfOrigin": {
          "@id": "https://ld.amazonalexa.com/entities/v1/...",
          "@type": [
            "Country"
          ],
          "name": [
            {
              "@value": "United States",
              "@language": "en"
            }
          ]
        }
      }
    
  • Functional and transient – A Country has one politicalLeader, but the value does change over time. This property returns an array. The value in the array represents the value at the current point in time, not historical values.

      {
        "politicalLeader": [
          {
            "@id": "https://ld.amazonalexa.com/entities/v1/...",
            "@type": [
              "Person"
            ],
            "name": [
              {
                "@language": "en",
                "@value": "Justin Trudeau"
              }
            ]
          }
        ]
      }
    
  • Transient – A Country can have multiple borderingCountry values because a country can border multiple other countries. Country names and borders also change over time. This property returns an array that might contain any number of values.

      {
        "borderingCountry": [
          {
            "@id": "https://ld.amazonalexa.com/entities/v1/...",
            "@type": [
              "Country"
            ],
            "name": [
              {
                "@language": "en",
                "@value": "United States"
              }
            ]
          }
        ]
      }
    

JSON-LD reserved keywords

The JSON-LD syntax uses the @ sign in property names that represent reserved keywords. To access these properties in languages like JavaScript, use bracket notation instead of dot notation.

Bracket notation in JavaScript

name[0]['@value'] // returns "Canada" (the first name value in the array)
politicalLeader[0].name[0]['@value'] // returns Justin Trudeau

Missing properties and values

Alexa provides you with expected properties for each entity type. Not every entity returns the full set of possible properties. For example, not every Person entity has a deathdate property. Alexa leaves out of the JSON response all properties that aren't available. In your code, check for the presence of a property before attempting to access data.

The Linked Data API might also return incomplete lists of values. For example, a person might have eight children but the API might know about (and return) only four of those children. Don't use the API to answer questions about data completeness. For instance, if you want to know the total number of children that an actor has, don't count the number of elements in the child property of the entity that represents that actor.

Full example of a JSON-LD response

The following example illustrates a JSON-LD document that represents a Country entity in the Alexa knowledge graph.

Class hierarchy and inheritance

The following diagram illustrates the hierarchy of Alexa Schema classes. You can use the Linked Data API to explore these classes. Classes inherit properties from their parent classes. For example, entertainment:Actor inherits properties that apply to Artist, but can also have its own specific properties, such as castMemberOf.

This inheritance hierarchy diagram shows the root class Thing with the classes that inherit from it directly and indirectly, like Agent, Place, City, Book, and Region.
Class Hierarchy

Entity classes and properties

For details about the property types, see Alexa Entities and JSON-LD syntax.

The List column indicates whether the property returns a single value or an array of values. For more about how this is determined, see When does a property return a single object or an array?.

AnimalType

Represents the type of the animal, such as a species or breed. For example, lion is an AnimalType.

Property Description Type List Example Value
name A descriptive name for the type of animal. rdf:PlainLiteral Yes "zebra"
typicalGestation The duration of the typical full-term pregnancy for this animal. xsd:duration Yes "P376D"
typicalHeight The typical height of this type of animal. asd:Distance Yes 129.54
typicalLength The typical length of this type of animal. asd:Distance Yes 235
typicalLifespan The typical length of time that an animal of this type lives. xsd:duration Yes "P25Y"
typicalWeight The typical weight of an animal of this type. asd:Mass Yes 219

AudioTrack

An audio track is an audio work that consists of a single stream of recorded sound and that can be featured in a collection of audio tracks, such as an audio playlist. For example, "Bridge Over Troubled Waters" is an audio track. "Radiolab" isn't an audio track.

Property Description Type List Example Value
audioTrackVersion:album The collection of recordings that include the audio track. MusicAlbum Yes "Highway 61 Revisited"
audioWork:artist The artist or artists associated to the audio work as the main performer or performers. Artist Yes "Bob Dylan"
name The name of the audio track rdf:PlainLiteral Yes "Like a rolling stone"
runtime The length of time that the creative version lasts. xsd:duration No "PT6M9S"

Book

A book is a written work that uses words and pictures to represent knowledge or a fictional story. A book is often in bound paper and ink or it can be an e-book. For example, Harry Potter and The Chamber of Secrets is a Book.

Property Description Type List Example Value
entertainment:author The author of the book. entertainment:Author Yes "J. K. Rowling"
name The primary title for the book. rdf:PlainLiteral Yes "Harry Potter and The Chamber of Secrets"
version The version of the creative work. CreativeVersion Yes See BookVersion

BookVersion

A book version is a written version that uses words and/or pictures to represent knowledge or a fictional story, often manifested in bound paper and ink, or in e-books. A book version is also a specific version of a book. For example, The Italian first edition of the book Harry Potter and the Chamber of Secrets is a BookVersion.

Property Description Type List Example Value
name The primary title for book version rdf:PlainLiteral Yes "Harry Potter e la Camera dei Segreti"
publisher The agent that prepares and issues the creative version for sale. Agent Yes "Bloomsbury Publishing Plc"
releaseEvent The event or events that took place when the book version was released in various countries. ReleaseEvent Yes See ReleaseEvent

City

A city is a human settlement of significant size. For example, Liverpool is a City.

Property Description Type List Example Value
averageElevation The average height above sea-level in meters for a geographical area. asd:Distance Yes 115
capitalOf The place for which this city is the primary governing city or town. Place Yes "France"
humanPopulation The number of people who live in a geographical area. xsd:integer Yes 2148000
locatedWithin The place where the city is located. Place Yes "France"
name The name of the city. rdf:PlainLiteral Yes "Paris"

Country

A country is a geographical area whose extension corresponds to a sovereign state or former sovereign state, and whose territory is internationally recognized as a political or cultural entity. For example, France is a country.

Property Description Type List Example Value
borderingCountry A country with which this country shares a border. Country Yes "Belgium"
capital The primary governing city or town for a place. Settlement Yes "Paris"
currency A system of money used in a geographical area. Currency Yes "Euro"
humanPopulation The number of people who live in a geographical area. xsd:integer Yes 65328864
name The name for the country. rdf:PlainLiteral Yes "France"
politicalLeader A person who occupies a position of leadership in the government of a place. Person Yes "Emmanuel Macron"

entertainment:Actor

An actor is an artist who portrays a character in one or more acted work versions. For example, Leonardo Di Caprio is an actor.

Property Description Type List Example Value
entertainment:castMemberOf The animated visual works in which the artist portrayed a character. AnimatedVisualWork Yes "Kill Bill Volume 1"
name The primary label for the actor. rdf:PlainLiteral Yes "Leonardo Di Caprio"
totalNumberOfAwards The number of awards that the actor has won. xsd:integer Yes 99

entertainment:Author

An author is an artist who creates the text within a written work or version. This type includes individual human authors and pseudonyms. For example, C.S. Lewis is an Author.

An Author entity might include Person properties as well.

Property Description Type List Example Value
entertainment:authorOf The books that this author has published. CreativeWork Yes "The Lion, the Witch and the Wardrobe"
name The name of the author. rdf:PlainLiteral Yes "C. S. Lewis"

entertainment:Director

A director is an entity who is known for directing animated visual productions such as films or TV shows. This includes individual human directors and combined entities such as director duos. For example, Sam Mendes is a director. Ben Affleck is both an actor and a director. The Coen Brothers duo is a director.

Property Description Type List Example Value
entertainment:directorOf The creative works for which the director is in charge of the creative aspects of the production. CreativeWork Yes "American Beauty"
name The name of the director. rdf:PlainLiteral Yes "Sam Mendes"
totalNumberOfAwards The number of awards that the director has won. xsd:integer Yes 4

entertainment:Musician

A musician is an artist who plays a musical instrument or is musically talented. For example, Ed Sheeran is a musician.

Property Description Type List Example Value
artist:album The artist's collection of recordings. MusicAlbum Yes "Piano Piano"
musician:band The music group to which the artist belongs. MusicGroup Yes "The Lumineers"
name The name of the musician. rdf:PlainLiteral Yes "Jeremiah Fraites"
artist:recordedSongVersion The song version or versions that the artist has recorded and released. SongVersion Yes "Maggie"

Movie

A movie is an animated visual work that consists of a series of moving pictures, often telling a story. For example, Pulp Fiction is a Movie.

Property Description Type List Example Value
countryOfOrigin The country in which the movie originated. Place No "United States"
entertainment:castMember An artist who acts to portray a character in the animated visual work. entertainment:Actor Yes "Tim Roth"
entertainment:director The artist who is in charge of the creative aspects of the creative work. entertainment:Director Yes "Quentin Tarantino"
name The name of the movie. rdf:PlainLiteral Yes "Pulp Fiction"
version The version of the creative work. CreativeVersion Yes See MovieVersion

MovieVersion

A movie version is an animated visual version that consists of a series of moving pictures, often telling a story, usually shown in a theater or on television. A movie version is also a specific version of a movie. For example, "Kill Bill: Volume 2 (English Language, 2004)" is a MovieVersion.

Property Description Type List Example Value
name The name of the movie version. rdf:PlainLiteral Yes "Pulp Fiction"
releaseEvent The event or events that took place when the movie version was released in various countries. ReleaseEvent Yes See ReleaseEvent
runtime The length of time that the creative version lasts. xsd:duration No "PT154M"

MusicAlbum

A music album is an audio playlist that consists of a list of music tracks that were released as a collection and are available as a compact disk (CD), vinyl or on other media. For example, Abbey Road by The Beatles is a music album.

Property Description Type List Example Value
audioTrackVersion An audio track that's included in the audio playlist. AudioTrack Yes "At the Bottom of Everything"
audioWork:artist The artist or artists associated with the audio work as the main performer or performers. Artist Yes "Bright Eyes"
name The name of the music album. rdf:PlainLiteral Yes "I'm Wide Awake, It's Morning"
numberOfTracks The number of audio tracks included in the audio playlist. xsd:integer No 10
releaseEvent The event or events that took place when the movie version was released in various countries. ReleaseEvent Yes See ReleaseEvent
runtime The length of time that the creative version lasts. xsd:duration No "PT45M"

MusicGroup

A music group is a performing group that performs music. For example, The Beatles are a music group.

Property Description Type List Example Value
artist:album The artist's collection of recordings. MusicAlbum Yes "Cassadaga"
dateFounded The date and time when the music group was established. asd:DateTime No "1995"
member An Agent who is part of music group. Agent Yes "Conor Oberst"
name The name of the music group. rdf:PlainLiteral Yes "Bright Eyes"
numberOfMembers The number of individuals belong to the music group. xsd:integer Yes 3
artist:recordedSongVersion The song version or versions that have been recorded and released by the artist. SongVersion Yes "Lime Tree"

Person

A person is an animal that's a member of the human race and a member of the Homo Sapiens species. For example, Alexander Hamilton is a Person.

Property Description Type List Example Value
birthdate The point in time when the person was born. asd:DateTime No "1755-01-11"
birthplace The place where the person was born. Place No "Charlestown"
child The person's child or children Person Yes "Alexander Hamilton Jr."
deathdate The point in time when the person died. asd:DateTime No "1804-07-12"
deathplace The place where the person died Place No "Greenwhich Village"
name The name of the person. rdf:PlainLiteral Yes "Alexander Hamilton"
occupation The person's source of livelihood. Also includes roles that are unpaid but take up the majority of the person's productive time, such as full-time careers and unpublished novelists. Occupation Yes "politician"

ReleaseEvent

A release event is an individual event consisting of releasing a product to customers. For example, the event of Blade Runner International Version being released in Japan.

Property Description Type List Example Value
startDateTime The start day and time for an event. asd:DateTime Yes "1994-10-14"

TvSeries

A TV series is an animated visual work that consists of a set of connected episodes that constitute a program transmitted on television or on other broadcasters such as Netflix, Amazon Prime and similar. For example, The Good Place is a TV series.

Property Description Type List Example Value
entertainment:castMember An artist who acts to portray a character in the animated visual work. entertainment:Actor Yes "Claire Foy"
name The name of the TV series. rdf:PlainLiteral Yes "The Crown"
numberOfEpisodes The number of episodes in a TvSeries or podcast. xsd:integer No 40
numberOfSeasons The number of seasons in a TvSeries. xsd:integer No 4

Data types

Each data property has a type. These types are in the namespace https://schema.amazonalexa.com/datatypes/1.0/.

Name Description / Example Value Standard

asd:DateTime

{
  "@value": "2019-07-02T19:27:57Z",
  "@type": "asd:DateTime"
}

ISO 8601

asd:Distance

{
  "@value": "29086",
  "@type": "unit:Feet"
}

The asd:Distance type is expressed in the form of the unit of distance, such as unit:Feet. Unit of distance examples:

  • Inch: {"@value":"2","@type":"unit:Inch"}
  • Foot: {"@value":"2","@type":"unit:Foot"}
  • Millimeter: {"@value":"2.3","@type":"unit:Millimeter"}
  • Centimeter: {"@value":"12.5","@type":"unit:Centimeter"}
  • Meter: {"@value":"12.5","@type":"unit:Meter"}
N/A

asd:Mass

{
  "@value": "1950.45",
  "@type": "unit:Kilogram"
}

The asd:Mass type is expressed in the form of a unit of mass, such as unit:Kilogram. Unit of mass examples:

  • Pound: {"@value":"2","@type":"unit:Pound"}
  • Gram: {"@value":"2.3","@type":"unit:Gram"}
  • Kilogram: {"@value":"12.5","@type":"unit:Kilogram"}
N/A

rdf:PlainLiteral

A localized string value. The object returned for this type has a @language property, but not a @type property.

{
  "@value": "zebra",
  "@language": "en-US"
}

Use the Accept-Language header in the Linked Data API call to specify the locale returned.

rdf:PlainLiteral

xsd:duration

{
  "@value": "PT10M",
  "type": "xsd:duration"
}

XML Schema

xsd:integer

{
  "@value": "12",
  "@type": "xsd:integer"
}

XML Schema