How to rapidly develop applications on Amazon Cloud Directory with Managed Schema

Now, Amazon Cloud Directory makes it easier than ever for you to rapidly develop applications by using Managed Schema. You can create a directory and start creating and retrieving objects from it at a faster pace by using the managed schema. With this launch, we are making available one Cloud Directory Managed Schema, called QuickStartSchema. You can build a rich hierarchical data model and establish relationships across objects by using constructs such as Typed Links from Cloud Directory. You can then query for any information in your data by traversing the hierarchy.

Cloud Directory is also introducing a new style of facet called Dynamic facet. This enables you to rapidly prototype your application as you can start without defining any attributes in your facet. You can add new attributes or change the value stored for your attributes to any other supported data type at a later time as you further develop your application.

Cloud Directory is also introducing new data type called Variant. To store values for the attribute defined as a Variant data type, you can use values of any of the primitive data types supported in Cloud Directory, such as String or Binary. Over time, you can also change the value of the attribute to another data type. There is no enforcement of data validation.

Cloud Directory has defined one facet in the QuickStartSchema as Dynamic style. This enables you to create any number of attributes that you need for your application. When you create any attribute using this facet, it is created as Variant data type.

In this blog post, I demonstrate how to create an application that helps me track students in my school sports teams. I use Cloud Directory and the new QuickStartSchema. I create one dimension for the students and a second dimension for the sports teams. I add information for the students and teams to my directory and query for data.

The example in this blog post uses Java code. I have assumed that you are familiar with the AWS SDK and can use Java-based code to build a Cloud Directory code example. Feel free to apply the concepts I show in this post to other programming languages such as Python and Ruby.

Using Cloud Directory Managed Schema for rapid development

I am keen to rapidly develop a sports team directory application and start using it soon. I need hierarchical data and queries that traverse my hierarchy. Because the type of data that I am storing, such as student name and sports team names, doesn’t have a fixed set of predetermined values, I don’t need the data type and constraint checking that is provided by Cloud Directory static facet. My needs match the features being offered by the Cloud Directory QuickStartSchema. The schema enables me to develop an application and use the features of Cloud Directory such as hierarchical queries. Using this schema, I can directly create my directory, thus saving time and effort on a schema creation and management process (schema lifecycle explained in an earlier blog post).

The application tracks students who are members of different sports teams such as football or badminton. I show the data model below. I have created a simple hierarchy under Student pool to represent students who are members of the sports teams. Similarly, I am representing the different sports teams in another hierarchy. I use Typed Links to establish the relationship between a student and a sports team.

The Managed Schema called QuickStartSchema is available to all Cloud Directory customers and can be directly referenced by a constant ARN.

Within the QuickStartSchema, Cloud Directory has defined one dynamic facet called as DynamicObjectFacet. I can use this facet to create objects of type NODE, LEAF_NODE or POLICY. For my application, I create StudentPool as a NODE object and students Jane and Jim as LEAF_NODE objects. Similarly, within the QuickStartSchema, Cloud Directory has also defined one Typed Link facet called as DynamicTypedLinkFacet, which has one attribute called as DynamicTypedLinkAttribute. I use this Typed Link to establish relationships between the students and the teams.

Create a directory using the QuickStartSchema

The following code creates my directory called SportsTeamDirectory using the QuickStartSchema ARN. I get values for applied schema ARN and directory ARN. As you can see from the following code example, I don’t need to create and publish a schema.

// Create a directory using the QuickStartSchema. Specify a 
// directory name that must be unique within an AWS account. 

String QUICK_START_SCHEMA_ARN = "arn:aws:clouddirectory:::schema/managed/quick_start/1.0/001" ;

CreateDirectoryRequest createDirectoryRequest = new 
	CreateDirectoryRequest()
    .withName("SportsTeamDirectory") // Directory name
    .withSchemaArn(QUICK_START_SCHEMA_ARN);

CreateDirectoryResult createDirectoryResult = 
	client.createDirectory(createDirectoryRequest);

String directoryArn = createDirectoryResult.getDirectoryArn();
String appliedSchemaArn = createDirectoryResult.getAppliedSchemaArn();

Create objects in the directory

The following code creates objects by using the attributes as a map of key-value pairs to be stored on an object.

// Create “Student pool”, student and team objects 

Map<String, String> studentPoolAttributeMap = new HashMap<>();
studentPoolAttributeMap.put("Name", "StudentPool");

String studentPoolObjectId = createDirectoryObject("/", "Students", studentPoolAttributeMap, ObjectType.NODE);

Map<String, String> janeAttributeMap = new HashMap<>();
janeAttributeMap.put("Name", "Jane");
janeAttributeMap.put("EmailAddress", "jane@someschool.edu");

String janeObjectId = createDirectoryObject("/Students", "Id-123", janeAttributeMap, ObjectType.LEAF_NODE);

/**
* You can use similar code to create objects for all the students and teams
* 
* The following code example defines a helper method called “createDirectoryObject” to
* create objects. “DynamicObjectFacet” is a Cloud Directory defined facet
* available in QuickStartSchema to create objects.
*/
private String createDirectoryObject(String parentReference, String linkName, Map<String, String> attributeMap, ObjectType objectType) {
              List<AttributeKeyAndValue> attributeList = new ArrayList<>();

              for (Map.Entry<String, String> entry : attributeMap.entrySet()) {
                     attributeList.add(new AttributeKeyAndValue()
                                  .withKey(new AttributeKey()
                                                .withSchemaArn(appliedSchemaArn)
                                                .withFacetName("DynamicObjectFacet")
                                                .withName(entry.getKey()))
                                  .withValue(new TypedAttributeValue().withStringValue(entry.getValue())));
              }

              // This ARN is provided by Cloud Directory and contains definitions for object types such as Node and Leaf_Node.
             String cloudDirectorySchemaArn = "arn:aws:clouddirectory:<region>:<accountId>:directory/<directoryId>/schema/CloudDirectory/1.0";

              List<SchemaFacet> schemaFacets = Arrays.asList(
                           new SchemaFacet().withSchemaArn(appliedSchemaArn).withFacetName("DynamicObjectFacet"),
                           new SchemaFacet().withSchemaArn(cloudDirectorySchemaArn).withFacetName(objectType.name()));

              return client.createObject(new CreateObjectRequest()
                           .withDirectoryArn(directoryArn)
                           .withSchemaFacets(schemaFacets)
                           .withParentReference(new ObjectReference().withSelector(parentReference))
                           .withLinkName(linkName)
                           .withObjectAttributeList(attributeList)).getObjectIdentifier();
       }

Create relations between objects by using typed links

QuickStartSchema provides a typed link facet with a single variant-typed identity attribute. I can use this to create typed links between objects that would hold a single identity attribute over it.

/**
* “DynamicTypedLinkFacet” and “DynamicTypedLinkAttribute” are Cloud Directory
* defined Typed Link facet and attribute names, available in the QuickStartSchema.
* I cannot change these names.
**/
       private AttachTypedLinkResult attachDirectoryTypedLink(String sourceObjectId, String destinationObjectId,
                     String typedLinkAttributeValue) {
              TypedLinkSchemaAndFacetName typedLinkSchemaAndFacetName = new TypedLinkSchemaAndFacetName()
                            .withTypedLinkName("DynamicTypedLinkFacet").withSchemaArn(appliedSchemaArn);

              return client.attachTypedLink(new AttachTypedLinkRequest().withDirectoryArn(directoryArn)
                           .withTypedLinkFacet(typedLinkSchemaAndFacetName)
                           .withAttributes(new AttributeNameAndValue()
                                         .withAttributeName("DynamicTypedLinkAttribute")
                                         .withValue(new TypedAttributeValue().withStringValue(typedLinkAttributeValue)))
                           .withSourceObjectReference(new ObjectReference().withSelector(sourceObjectId))
                           .withTargetObjectReference(new ObjectReference().withSelector(destinationObjectId)));
       }

AttachTypedLinkResult result = attachDirectoryTypedLink(janeObjectId, lionsObjectId, "Captain");

Retrieve data from directory

After creating the objects and establishing the hierarchies, I can perform either a path or identifier-based query to fetch data from Cloud Directory. For example, I can use ListObjectAttributesRequest to perform a path-based query for my attribute keys and values.

Best Practices for using Dynamic Facet vs Static Facet

When you need flexibility to change the number of attributes or change the data values being stored within your attributes, you can use a dynamic facet. Cloud Directory does not enforce any data constraints and rule checking during your object creation or change.

Use a static facet when these conditions apply: First, you have all the details of your data model for your directory, such as list of attributes with its data types. Second, you want to define constraints for your attributes, such as mandatory or unique fields. Cloud Directory enforces the data constraints and rule checking during your object creation or change.

You can also combine the static and dynamic facets within a single schema to get benefits for each style of facet within your directory.

About Cloud Directory

Cloud Directory is a high-performance, fully managed, hierarchical data store. It’s a highly scalable, multi-tenant service that makes it easy for you to organize and manage all your multi-dimensional data. Multi-dimensional data might include users, groups, locations, devices, and the rich relationships between them.

You can build different dimensions of data using Schema facets to define the objects within these dimensions (such as employees, devices, locations). Cloud Directory is ideal for hierarchical data and can traverse the hierarchies to collect information along the paths in an efficient manner. Other characteristics are high read-to-write ratio and data sets with low amount of storage. Cloud Directory is targeted for use cases such as human resources applications, course catalogs, device registry, and network topology. Additionally, if your application requires fine-grained permissions (Authorization), then it’s well suited to use the capabilities in Cloud Directory.

Summary

You can use Cloud Directory Managed Schema for rapid prototyping and development for your application. You can build rich hierarchies of data and query for it by using hierarchy traversals. For more information about Managed Schema, Dynamic Facet, or Variant Data Type, see the Cloud Directory Schema documentation.

If you have comments about this blog post, submit them in the “Comments” section below. If you have questions about implementing the solution in this post, start a new thread in the Directory Service forum or contact AWS Support.

About the Author

Mahendra Chheda is a principal product manager at Amazon Web Services.

Shivam Gujral is a software development engineer at Amazon Web Services.