Creating Enumerated Properties : Help

In Freebase, an enumerated property is a special property that writes its values to a namespace. It is used to assign unique namespace values to a topic, and can be used to optionally create a URI template that uses that property value. For example, a Netflix or IMDb ID could be an enumerated property on the type /film/film. When a value for that property is entered in a film topic, the value is added as a key for the namespace for which that property enumerates. For example, the type film/film has an enumerated property IMDb Profile Page, where you would enter in the IMDb ID of a movie.

Another advantage of property enumerations is that because the property value is entered as a key into a namespace, Freebase can alternatively identify the topic using the namespace URI. For example, http://www.freebase.com/view/guid/9202a8c04000641f8000000000b14838 and http://www.freebase.com/view/authority/imdb/title/tt0259822 both refer to the film .45. The id preference of a topic depends on namespace depth and priority, where Freebase prefers /en namespace, then the shortest namespace next (and finally /guid/*). Note that authority is a reserved namespace used only for "authoritative" sources such as IMDb, Amazon, GNIS, etc., and that only superusers have access to this namespace.

An enumerated property can be used in a typical domain, or in a namespace. Creating a unique namespace and tying it to a unique enumerated property within that namespace ensures, however, that any topic you create in that namespace which uses your enumerated property will itself be unique. Non-unique enumerations allow a many-to-one unique key to topic mapping (a topic can have multiple unique keys). Creating a unique namespace and tying it to a unique enumerated property within that namespace ensures a one-to-one object mapping to one and only one unique key in the namespace (a topic cannot have more than one key). Another advantage is that creating an enumerated property in a namespace ensures the uniqueness of values for that property, and, by extension, a unique naming of object keys for any object that has that property attached. You must make sure, however, that both the namespace and property are marked as unique, or there will be a conflict.

This topic will take you through the steps of creating a namespace, and an enumerated property in that namespace. See the topic Creating a URI Template for information on how to use your enumerated property within a URI template.

Create a Domain and Namespace

Before you create a namespace, you should create a domain that has the same name. This will provide the namespace with an object that it can key into (whenever you create an object in Freebase you are basically creating something that is keyed to another object) and will provide you with fairly transparent relationship between the domain and the namespace. The namespace and the domain don't have to have the same name, but giving both same or similar names will make everything easier to track.

One wrinkle in this is that even though the domain you create has write permissions that are restricted to your user ID, anything created as a result of a mqlWrite command, such as a namespace, has global write permissions. The way around this is to use the use_permission_of parameter in the outer envelope of the mqlWrite command.

Create a domain, either in the client or through mqlWrite, whichever you prefer. In this case it would be called My DJ Tracks, and would have a key of my_dj_tracks.
Paste the mqlWrite command below, with your information replacing the examples, into the query editor and click Write. This will connect the namespace My DJ Tracks to the domain of the same name.

"q1" : {
  "query" : {
    "create" : "unconditional",
    "id" : null,
    "name" : {
      "lang" : "/lang/en",
      "value" : NAME_OF_NAMESPACE
    },
    "type" : "/type/namespace",
    "unique" : {
      "value" : true
    }
  }
},
"use_permission_of" : ""
}

To find the permission of your domain, you'll need to use the explore view (available in the Developer's Toolbar at the bottom of the page, press F8 while on a Freebase.com page to open the toolbar) and find the permission object linked to the domain (something like owner of USER'S domain)

Important: Make sure to note the guid that is associated with your new namespace when Freebase responds to your mqlWrite command. You will need this to connect the enumerated property you're creating in the next step with the namespace.

Create a Type and the Enumerated Property in the Namespace

Now that you have a domain and a unique namespace, you can go through the process of creating a type, and its attendant properties, as you normally would. After that, you connect the enumerated property to the namespace.

Navigate to the domain you've created through Freebase.com.
Using the schema editor, create a type that will contain your enumerated property, for example, DJ Track.
Create your enumerated property as you would any other property. Select Link to a Topic for the data type, then enter enumeration. Select the enumeration/Metaweb System type, then save. You'll notice that instead of having the icon for linking to another topic, the icon for a text field now appears next to your property name.
When you're done creating your type and the enumerated property, you need to connect the enumerated property to the namespace you've created, and make it unique. In your browser URI window enter the following URI:

http://www.freebase.com/view/user/{your user name}/{domain name}/{type name}/{property name}?admin=1

This opens the admin view for the property you've created.

Click 7 empty fields under Property to view all the properties of this property.
Click edit next to unique, enter Yes, and save.
Click edit next to enumeration, enter /guid/[the guid of your namespace], and save.