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.

• English (AU)
• English (CA)
• English (IN)
• English (UK)
• English (US)
• French (FR)
• German (DE)
• Italian (IT)
• Spanish (ES)

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:langString).
• @language: Included for a localized string (rdf:langString) values. A locale 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:langString 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 Person has one birthplace, and this value doesn't change over time. This property returns a single object.

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

• 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.

JSON-LD for a Country entity  

{
  "@context": {
    "@vocab": "https://schema.amazonalexa.com/core/1.0/",
    "@type": {
      "@id": "type",
      "@container": "@set"
    },
    "borderingCountry": {
      "@id": "https://schema.amazonalexa.com/core/1.0/borderingCountry",
      "@container": "@set"
    },
    "capital": {
      "@id": "https://schema.amazonalexa.com/core/1.0/capital",
      "@container": "@set"
    },
    "currency": {
      "@id": "https://schema.amazonalexa.com/core/1.0/currency",
      "@container": "@set"
    },
    "humanPopulation": {
      "@id": "https://schema.amazonalexa.com/core/1.0/humanPopulation",
      "@container": "@set"
    },
    "name": {
      "@id": "https://schema.amazonalexa.com/core/1.0/name",
      "@container": "@set"
    },
    "politicalLeader": {
      "@id": "https://schema.amazonalexa.com/core/1.0/politicalLeader",
      "@container": "@set"
    },
    "xsd": "http://www.w3.org/2001/XMLSchema#"
  },
  "@id": "https://ld.amazonalexa.com/entities/v1/KergWGkJmd9FT9YSvzn3AL",
  "@type": [
    "Country"
  ],
  "borderingCountry": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/AJGFaH8FpvdBHPuUlYi9rX",
      "@type": [
        "Country"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "United States"
        }
      ]
    }
  ],
  "capital": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/4UReWIgsWRxD1BJaIUA2Ad",
      "@type": [
        "City"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Ottawa"
        }
      ]
    }
  ],
  "currency": [
    {
      "@type": [
        "Currency"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Canadian dollar"
        }
      ]
    }
  ],
  "humanPopulation": [
    {
      "@type": "xsd:integer",
      "@value": "37700000"
    }
  ],
  "name": [
    {
      "@language": "en",
      "@value": "Canada"
    }
  ],
  "politicalLeader": [
    {
      "@id": "https://ld.amazonalexa.com/entities/v1/4v7JvEnQrCSDpwtl6qA05A",
      "@type": [
        "Person"
      ],
      "name": [
        {
          "@language": "en",
          "@value": "Justin Trudeau"
        }
      ]
    }
  ]
}

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?.

The Availability column indicates whether the property is available or in public beta.

• Available – The type or property is fully available. The name and data structure for the property are considered stable and won't change.
• Public beta – The type or property is offered in public beta. Its name and/or data structure might change or improve as we learn more from developers.

For all properties, data returned by Alexa Entities might change, for example when Alexa learns a new fact or a value is updated.

AnimalType

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

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.

AudioTrackVersion

An audio track version is an audio version that consists of a single stream of recorded sound. It is also a specific version of an audio track. Come Together (remastered 2009) is an audio track version in the music album Abbey Road 1969 (Remastered 2009) on Spotify.

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.

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.

City

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

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.

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.

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.

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.

entertainment:Musician

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

FoodType

Food type is a class of foods encompassing prepared dishes as well as individual food items.

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.

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.

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.

MusicAlbumVersion

A music album version is an audio playlist version that consists of a list of music track versions that are released as a collection and are available as a compact disk (CD), vinyl or on other media. It is also a version of a music album. Revolver (Remastered) by The Beatles is a music album version.

MusicGroup

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

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.

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.

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.

Data types

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

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

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

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

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

{
    "@type": "xsd:boolean",
    "@value": "true"
}

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

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

Sample code

The following sample code demonstrates how to build a skill that uses Alexa knowledge graph:

• Alexa Entities Python Demo

Related topics

• Linked Data API Reference
• Entity Resolution for Built-in Slot types
• Entity Resolution

Last updated: Nov 28, 2023