Understanding Tag Formats for Content Creation and Filtering

This article details the various forms in which Tags can be expressed when interacting with the Learnosity APIs.

Tags can be associated to Items to ease authoring and Item retrieval as well as reporting and analytics. They consist of a type and a name.

For example, an Item testing the persuasive writing of a student in 10th grade, according to the Common Core curriculum could be assigned the following Tags:

Type Name
Subject English
Grade 10
Standard CCSS.ELA-LITERACY.WHST.9-10.1 - Persuasive Writing

 

Note that an Item can be Tagged with more than one Tag of a specific type; it is also possible for two Tags of different type to share the same name.

When manipulating data or searching, Tags can be represented in a few different ways depending on the purpose. In some cases, the object formats are versioned. However, the most common objects/versions are as follows.

Tags objects (Data)

Learnosity APIs may use various Tag representations with names as follows:
  • TagsV2 represents a single Tag and its metadata.
  • TagsV1 represents a single Tag type with a collection of Tag names.
  • TagsV0 represents a collection of Tag types with corresponding Tag names for each type. This format is now deprecated.

A TagsV2 object represents a single Tag and its metadata.

The object has the following properties:

  • type: string Tag type. Note that all Tag names belong to a Tag type.
  • name: string Tag name.
  • Other properties may describe Tag metadata, like description and sort_key.

 

Multiple Tags from the same or different Tag types can be represented as a flat array of TagsV2 objects. It is used, for example, in getTagHierarchyNodes.

 

[
  {
    "type": "TYPE1",
    "name": "NAME1"
  },
  {
    "type": "TYPE1",
    "name": "NAME2"
  },
  {
    "type": "TYPE2",
    "name": "NAME3"
  },
  {
    "type": "TYPE2",
    "name": "NAME4"
  }
]

TagsV2 object with additional Tag name metadata

{
  "type": "TYPE2",
  "name": "NAME1",
  "description": "DESCRIPTION_NAME1",
  "sort_key": 1
}

TagsV1

A TagsV1 object represents a single Tag type with a collection of Tag names.

The object has the following properties:

  • type: string Tag type.
  • tags: Object[] where each object contains a namestring property, and optional other metadata properties for the Tag name such as description and sort_key.

 

Tags from multiple Tag types can be represented by putting multiple TagsV1 objects in an array. This format supports carrying additional information about each Tag (such as a description) while not duplicating the type information.

 

[
  {
    "type": "TYPE1",
    "tags": [
      { "name": "NAME1" },
      { "name": "NAME2" }
    ]
  },
  {
    "type": "TYPE2",
    "tags": [
      { "name": "NAME3" },
      { "name": "NAME4" }
    ]
  }
]

TagsV1 object with additional Tag name metadata

{
  "type": "TYPE2",
  "description": "DESCRIPTION_TYPE2",
  "tags": [
    { "name": "NAME3", "description": "DESCRIPTION_NAME3" },
    { "name": "NAME4", "description": "DESCRIPTION_NAME4" }
  ]
}

TagsV0 Deprecated

A TagsV0 object represents a collection of Tag types with corresponding Tag names for each type. The properties of the object are types, and they contain arrays of Tag names within that Tag type.

{
  "TYPE1": [ "NAME1", "NAME2", ...],
  "TYPE2": [ "NAME3", "NAME4", ...]
}

TagType objects (Data)

TagType objects are used when creating or retrieving Tag types. These simple objects comprise two properties.

  • name: the name of the type
  • description: the friendly description for the type, set to null if unspecified

TagType objects are returned, for example, by the getTagHierarchies endpoint.

 

[
  {
    "name": "TYPE1",
    "description": "A user-friendly description of Tag type 1"
  },
  {
    "name": "TYPE2",
    "description": null /* A Tag-type with no user-friendly description */
  }
]

Search by Tags (Request)

Tags can be used in search queries to find corresponding sets of Items and Activities. Note that only type and name are used for the purpose of searching the Item bank. Depending on the requirements, the following objects can be used to express Tags as search parameters:

 

Tag-based searches are case insensitive for { both types and names. It is also possible to do wildcard searches, by using the TagSearchByType object, as described next.

TagSearchByType

A TagSearchByType object represents a wildcard search by tag-type, and its metadata. It does not contain Tag names. They are used in Author API browse controls and searches by Tags, as described in the rest of this section.

The Tag type object has the following properties:

  • type: string Tag type.
  • Other properties may describe metadata, like description and label, to be used when rendering Tag search UI.

 

TagSearchByType with additional Tag type metadata

{
  "type": "TYPE2",
  /* no name */
  "description": "TYPE2_DESCRIPTION",
  "label": "TYPE2_UI_LABEL"
}

SimpleTagSearchParams (Author API)

The simple Tag search format uses TagsV1 objects or TagSearchByType objects

Items or Activities suitable for two grades

{
  "type": "Grade",
  "tags": [
    { "name": "Grade 7" },
    { "name": "Grade 8" }
  ]
}

Items or Activities tagged for any subject

{
  "type": "Subject"
}

AdvancedTagSearchParams (Data API)

Advanced search allows you to specify more complex queries, including optional or negative criteria. An advanced Tag search comprises three sections, and only Items matching each of the section will be returned. Any of the sections can be omitted.

  • all: an array of TagsV2 objects or TagSearchByType objects; only Items and Activities with all those Tags will match
  • either: an array of
    • TagsV2 objects; Items and Activities with at least one of those Tags will match
    • arrays of TagsV2 objects; Items and Activities with at least one of those Tags from each set will match
  • none: an array of TagsV2 objects; Items and Activities with none of those Tags will match

Those sections will be combined to form a request with the following meaning.

  • all of the all Tags
  • AND at least one of the either Tags (or at least one Tag out of each either Tag array)
  • AND none of the none Tags

This format is used in the the filter.tags object in the Author API initialisation configuration, getItems and getActivities Data API endpoints, via the advanced_tags property. Note that if only an all-type search is needed, those endpoints support a simpler search, by placing the all tags array in the tags property of the request.

Math Items or Activities tagged for grade 7

{
  "all": [
    { "type": "Subject", "name": "Math" },
    { "type": "Grade", "name": "Grade 7" }
  ]
}

Math Items or Activities tagged for any grade

{
  "all": [
    { "type": "Subject", "name": "Math" },
    { "type": "Grade" }
  ]
}

Items or Activities suitable for two grades

{
  "all": [
    { "type": "Grade", "name": "Grade 7" },
    { "type": "Grade", "name": "Grade 8" }
  ]
}

Items or Activities suitable for at least one of two grades

{
  "either": [
    { "type": "Grade", "name": "Grade 7" },
    { "type": "Grade", "name": "Grade 8" }
  ]
}

Items or Activities suitable for at least one of two subjects AND at least one of two grades

{
  "either": [
    [
      { "type": "Subject", "name": "Math" },
      { "type": "Subject", "name": "English" },
    ],
    [
      { "type": "Grade", "name": "Grade 7" },
      { "type": "Grade", "name": "Grade 8" }
    ]
  ]
}

Items or Activities not tagged for grade 7 or 8 (may return undesirably many results)

{
  "none": [
    { "type": "Grade", "name": "Grade 7" },
    { "type": "Grade", "name": "Grade 8" }
  ]
}

Math Items or Activities suitable for at least one of two grades

{
  "all": [
    { "type": "Subject", "name": "Math" }
  ],
  "either": [
    {
      "type": "Grade",
      "name": [ "Grade 7", "Grade 8" ]
    }
  ]
}

Math Items or Activities for grade 7 with no overlap with the neighbouring grades

{
  "all": [
    {
      "type": "Subject",
      "name": "Math" 
    }
  ],
  "either": [
    {
      "type": "Grade",
      "name": "Grade 7"
    }
  ],
  "none": [
    {
      "type": "Grade",
      "name": "Grade 6"
    },
    {
      "type": "Grade",
      "name": "Grade 8"
    }
  ]
}

Simplifying searches for getItems and getActivities requests

{
  /*
   * ...
   * get Items or get Activities request
   * ...
   */
  "advanced_tags": {
    "all": [
      { "type": "Subject", "name": "Math" },
      { "type": "Grade" }
    ]
  }
}

/* ... can be simplified as ... */

{
  /*
   * ...
   * get Items or get Activities request
   * ...
   */
  "tags": [
    { "type": "Subject", "name": "Math" },
    { "type": "Grade" }
  ]
}

ItemPoolTagSearchParams (Data API)

When creating Item pools in the Data API, Items and Activities can be included based on their Tags. This is done through the content.tags, content.item_tags and content.activity_tags

property of each of the pools to create. All three are arrays of objects, and can contain a combination of the following:

 

Note that required_tags and additional_tags behave in a similar fashion as all and either in the advanced search above.

 

{
  /*
   * ...
   * set Pools request; definition of a single pool
   * ...
   */
   "tags": [
     {
       "type": "Course"
       // tag name is optional
     },
     {
       "required_tags": [
         {
           "type": "Subject",
           "name": "Math"
         }
       ],
       "additional_tags": [
         {
           "type": "Grade",
           "name": "Grade 7"
         },
         {
           "type": "Grade",
           "name": "Grade 8"
         }
       ]
     }
   ]
   /* ... */
}
 
Was this article helpful?

Related articles


Did you arrive here by accident? If so, learn more about Learnosity.