Understanding types of meta-data and what travels with USD file


I am trying to understand the differences between different types of meta-data that can be applied to prims in Omniverse and how/if they travel with the USD file.

Below, is a list of the meta-data I am exploring, my understanding of what this meta-data is, and my assessment of how it travels with the USD file.

I may be misunderstanding large chunks of this or have over-looked the right documentation references. I welcome any direction for further research and input as to what I have wrong, or incomplete.

In addition to the exposed code of Extensions in Omniverse, I am using these sources:


  1. Kind - an ontology built with hierarchical structured tokens stored in the Kind registry file.
  • Prims carry with them a representative string as a token for their Kind value.

  • There is a Pixar-built-in, model-based, Kind hierarchy in the Kind registry that is likely to exist in most USD interpreters.

  • An extended (custom) Kind registry file does not travel with a USD file. If a stage is going to be created and interacted with from a USD file that leverages a custom Kind, the software building the stage needs to have the custom Kind registry file loaded into it somehow to take advantage of the expanded hierarchy.

  1. Attribute - This is a property of any type that can be assigned to a prim with a label and a value.
  • It travels with the USD file and is explicitly defined inside the prim in the USD file.

  • It does not need to be referenced anywhere else (other than code that would leverage it outside the USD file).

  • If using an attribute that is a token, the list of available tokens are encoded in each prim that has that attribute with an assigned value.

  1. Relationship - This is a property of a prim that is always a pointer via a path to a prim, attribute, or other relationship in the USD file.
  • Does this property utilize a pointer (persistent unique ID) that will update the path when the referenced object in the hierarchy is moved or is the path hard coded?

  • These form dependency graphs that load related objects when the primary object is loaded. This is often used for proxy models.

  • Relationships travel with the USD file as a property explicitly defined inside a prim.

  1. Tag - This is part of a Tagging Property Widget extension and allows for a core library of tags (tfTokens?) to be referenced by objects for assigning those tags to the object.
  • I have not gotten this to work yet. It shows “no asset paths found.” I assume I don’t understand its function well yet.

  • It appears that it requires a tag ‘server,’ which I assume hosts the tag library, but I have not accessed this yet. There is an ‘include Omni.kit.tagging’ file that I have been unable to expose thus far for further investigation.

  • I assume the assigned tags will travel with the USD inside the prim, but that the tag server will require some type of external file similar to the kind registry.

Thank you for any direction and insight you may have.


For the most part, everything authored with USD will travel with the USD file. The problem is that some USD clients may be missing USD schemas and plugins that will yield different results when you open the USD file in another client. I recommend using the USD Glossary for quick references: USD Terms and Concepts — Universal Scene Description 22.08 documentation. You can also save or convert your USDs as .usda so that you can open them in a text editor and see what’s actually encoded. Some corrections and notes from your list:

  1. Metadata refers to additional key/value pairs that can be stored on prims or properties. More info here: USD Terms and Concepts — Universal Scene Description 22.08 documentation. Attributes and Relationships are not Metadata.
  2. Attributes with token type do not encode the full list of possible values. These are defined and kept with the schema.
  3. Relationships targets are just lists of prim or property paths (strings). The targets might not exist (e.g. not loaded yet, speculative or simply invalid).
  4. There’s no hard dependency with Relationships or loading of related objects.
  5. Tags are a whole system in OV that indeed require a Nucleus server and the Tagging service running on Nucleus.
  6. If you’re looking for something simpler than Tags, you can encode custom attributes and customData metadata.

Thank you Mati,

When saving a USD file from omniverse, what is the method for saving the USD schema as well? It doesn’t appear to be encoded in the file when viewing it as a .usda.

  1. Reading the metadata definition, it seems to be another item for my list of property types. I will dive further into those.
  2. My assumption about Attributes is based on the .usda code for the project I am working in. The script is based off of the Example Properties extension ‘Hovercraft Wheels’ property. In the .usda, under the relevant prim, it looks like this:
token componentType = "GateValve" (
            allowedTokens = ["None", "GateValve", "WellPump", "PressureReliefValve", "PressureIndicator"]

Can you help clarify what I may have done wrong, or my understanding of these lines of code?
2a. Is the Example Properties extension ‘Hovercraft Wheels’ property an attribute? If so, could this same property be made with metadata instead? Assuming I am okay with losing the ability to vary over time and create sub-metadata.
3. Could a Relationship be replaced with an Attribute that has a value type of a list of strings, or are there differences between the two?
4. Is their any type of unique ID system for prims that travels with prim and references a hash table or similar quick lookup?
5. Can you point me to documentation where I can learn more about the Tagging service?

Thank you. I appreciate your helpful replies!


No problem. Take a look at my edits on my last reply. A colleague corrected a few things for me.

  1. allowedTokens is attribute metadata that can be authored, but not required. In OV, we use it to populate the combobox in the PropertyWidget for those attributes. Here’s the code from the omni.kit.property.example extension:

    2.a. Yes, it’s an attribute as per the code snippet above. Yes, it could be represented as metadata, but you wouldn’t be able to provide the allowedTokens anymore as you noted, for example.
  2. I suppose you could. Relationships have their own API and behaviour that you’d lose out on. For example, I don’t think you could easily replicate the prepend/append composition features or relationships.
  3. Prim Paths are the unique, hashable IDs. stage.GetPrimAtPath is your quick lookup.
  4. Tagging Extension — Omniverse Create documentation

Thank you. This thread is substantially accelerating my learning. I am going to continue in this thread as I refine my understanding of property types in USD. Let me know if you would prefer a new thread be started. For me, I would want to come across this full thread when searching for information to better understand property types in USD.

  1. Is ‘property types’ an appropriate term for the collection of things discussed in this thread? If so, and I can change the title of the thread, I will do so to make it more accurate.
    1a. In my next post I will try to summarize what I have learned and get some new corrections.
  2. Thank you for the link to Tagging. I realize now that when I thought I was searching all Omniverse documentation, I have been searching in filtered sub-domains. For anyone else who may have this problem, return to the root site when searching or make sure you are filtered appropriately for your needs. root site – https://docs.omniverse.nvidia.com/
  3. I cannot find documentation on the Relationship property. For example, understanding prepend/append composition features and syntax. Can you help direct me to this?
  4. If a prim moves in a USD hierarchy, do all the pointers to its Prim Path get updated to the new Prim Path?
    4a. If so, is this a feature of Relationship as opposed to Attribute?
    4b. Is there some value being stored or type being used for Prim Paths that is not a simple string? I am making the assumption that a simple string would not know to update the Prim Path without the contextual information that it represents a Prim Path, and some type of two-way link to the table(?) storing the Prim Paths.
  5. If token types are defined for attributes and stored in the schema, and custom Kind registry is part of the schema… When I export a USD file and use it in a new environment, how do I export and transport the relevant custom schema information?

Thanks Again!

  1. I don’t know if there’s a general term for metadata AND properties.
  1. Universal Scene Description: UsdRelationship Class Reference The AddTarget function lets you specify a position.
  1. Targets are not updated automatically.
    4b. When you’re working with prim paths, you’ll usually using the Sdf.Path class, but it doesn’t have an auto-update features.
  2. Schema definitions and Kinds registry don’t travel with the data. At most, you’d be able to see IsA types, applied API schemas, and the names of the Kinds used. I’ve seen interest from the USD community to at least list up front what schemas were used to author a USD.

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.