sample json categories array

sample.json Categories Array

This page is a partial example of how the "categories" key in the sample.json file is used by the sample browsers (Visual Studio, Eclipse, Visual Studio Code and CLI) to organize and present all of the available samples. For additional information on how the sample browsers consume this information see the sample browser wiki article.

To see the current organizational tree of released samples, use the oneapi-cli tool on Windows, Linux or Mac:

oneapi-cli --ignore-os

You can create a project from any sample presented by the oneapi-cli tool and inspect the "categories" key inside the sample.json file that is found in the root folder of that project. The oneapi-cli tool can be found in the dev-utilities/latest/bin folder in any installation of the oneAPI Toolkits.

To determine which categories your sample should be placed, connect with the Samples Working Group and the UI/UX team.

The categories presented here are for instruction only. The names and organization shown here do not define which category names should be used. They are here to help you understand how the "categories" field > defines a sample tree to be presented by the sample browsers.

An Example of sample.json Category Tree Organization

NOTE: a sample can belong to more than one category. See the "categories" array section in the Sample Browser Behavior wiki page for more details.

At the time of this writing (September 2020), all categories begin with "Toolkit/" at the root, even if the categories are not toolkit names. This is a requirement of the current Samples Browser implementations.

Multiple levels in the category tree are allowed. The '/' character is used as a separator. You can think of the "categories" array as defining the location in a directory tree of the respective sample(s).

NOTE: Sorry, but it is not possible to use the '/' character as part of a category name.

• Getting Started
  • Getting Started Sample #1 "categories": ["Toolkit/Getting Started"],
  • Getting Started Sample #2 "categories": ["Toolkit/Getting Started"],
  • etc.
• A Sample Major Category
  • A Sub-Category
    • Some Sample #1 "categories": ["Toolkit/A Sample Major Category/A Sub-Category"],
    • Some Sample #2 "categories": ["Toolkit/A Sample Major Category/A Sub-Category"],
    • ...
  • Another Sub-Category
    • Sub-Sub-Category
      • Another Sample #1 "categories": ["Toolkit/A Sample Major Category/Another Sub-Category/Sub-Sub-Category"],
      • Another Sample #2 "categories": ["Toolkit/A Sample Major Category/Another Sub-Category/Sub-Sub-Category"],
      • ...
    • Sub-Sub-#2
      • Sub Sub Sample #1 "categories": ["Toolkit/A Sample Major Category/Another Sub-Category/Sub-Sub-#2"],
    • Sub-Sub-#3
      • Really Deep!
        • Deep Sample #1 "categories": ["Toolkit/A Sample Major Category/Another Sub-Category/Sub-Sub-#3/Really Deep!"],
        • Deep Sample #2 "categories": ["Toolkit/A Sample Major Category/Another Sub-Category/Sub-Sub-#3/Really Deep!"],
        • ...
  • More
    • More Samples #1 "categories": ["Toolkit/A Sample Major Category/More"],
    • More Samples #2 "categories": ["Toolkit/A Sample Major Category/More"],
    • ...
• Another Major Category
  • Another Major Category Sample #1 "categories": ["Toolkit/Another Major Category"],
  • Another Major Category Sample #2 "categories": ["Toolkit/Another Major Category"],
  • Another Major Category Sample #3 "categories": ["Toolkit/Another Major Category"],
  • Another Major Category Sample #4 "categories": ["Toolkit/Another Major Category"],
  • ...
• More!
  • Even More Samples #1 "categories": ["Toolkit/More!"],
  • Even More Samples #2 "categories": ["Toolkit/More!"],
  • Even More Samples #3 "categories": ["Toolkit/More!"],
  • Even More Samples #4 "categories": ["Toolkit/More!"],
  • Even More Samples #5 "categories": ["Toolkit/More!"],
  • ...