NIEM Snippets

NIEM XML follows a regular, well-defined syntax. Snippets can be used to quickly and consistently fill in standard syntax, leaving users to fill in the blank or partially-filled in values for fields like name and definition. Snippets are currently provided for NIEM XML constructs.

• Overview
• Demo
• Available NIEM snippets
  • Property snippets
  • Type snippets
  • Combo snippets
  • Schema snippets
  • Other snippets
• Conventions
  • Blanks
  • Dots (…)
  • ALLCAPS
  • Ordering
• Using NIEM snippets with Oxygen
  • Import snippets
  • Use a snippet
  • Modify a snippet
  • Reload snippets

Overview

The following is an example of a snippet or a template to create a basic element in NIEM. It includes the standard schema syntax required by the NDR, but leaves the fields for the element’s name, type, and definition blank for the user to fill in:

<xs:element name="" type="" nillable="true">
  <xs:annotation>
    <xs:documentation></xs:documentation>
  </xs:annotation>
</xs:element>

This is a very simple example, but it’s the kind of thing schema developers have to do over and over again. There is often built-in support in XML editors, including Oxygen, for schema syntax, but those provide for a wider range of options than NIEM allows. These NIEM-specific snippets provide an easy way for developers to quickly stub out the exact syntax the NDR requires and focus on filling in the semantics. It’s easier, for example, to create a new augmentation when all you need to do is fill in the blanks rather than figure out how to get the syntax right as well.

There are over two dozen snippets provided, ranging from simple snippets for an individual concept, snippets that stub out an entire namespace, and snippets that provide templates for related concepts at the same time.

Snippets are also available on this site for users who do not have the Oxygen XML Editor. Go to the Reference / Concepts section, navigate to the appropriate topic, and copy/paste the relevant snippets from the XML or JSON sections to your editor of choice. For example, a snippet to create a new element is available here.

Demo

Load NIEM snippets into Oxygen in order to easily insert common templates into NIEM domain or IEPD extension schemas:

• Load NIEM snippets (see instructions below)
• Type niem into an XML schema file
• Hit Ctrl + Space (Windows) or Cmd + Space (Mac) to see a list of applicable snippets with names that begin with “niem”
• Find and select the appropriate snippet
• Fill in the empty or partially-filled fields; update default values as necessary

Available NIEM snippets

The snippets include some commonly-used default values. If the given defaults are wrong for your typical scenario, you can customize them in Oxygen. Some are tailored more for IEPD developers than domain modelers, especially those relating to default cardinalities. See the instructions on how to modify a snippet.

Property snippets

The following snippets provide template for various kinds of NIEM properties.

Type snippets

The following snippets provide templates for various kinds of NIEM types.

Combo snippets

The following snippets provide templates for two or more related NIEM components that are often built at the same time.

Schema snippets

The following snippets can be used to initialize a NIEM XML schema and includes a general template for the schema header, definition, local terminology section, and import statements.

Other snippets

The following snippets provide additional NIEM templates.

Conventions

Several conventions were used with the snippets.

Note that these too can be adjusted by modifying the snippets in Oxygen in case you would like the defaults set differently.

Blanks

Blanks are used for values where no helpful defaults can be provided.

Dots (…)

A set of ‘…’ characters were used in places where a field has been partially filled in but requires additional text. Otherwise, it might not be immediately obvious that something is missing.

For example, it may not be obvious that the following element name and type reference are incomplete:

<xs:element name="Code" type="CodeType" nillable="true">
  <xs:annotation>
    <xs:documentation></xs:documentation>
  </xs:annotation>
</xs:element>

Adding dots to indicate missing text helps highlight where updates need to be made. The dots also have the benefit of being invalid characters in a property or type name. Although still valid within definitions, Oxygen can at least easily show these as errors when they are left remaining in component names and references:

<xs:element name="...Code" type="...CodeType" nillable="true">
  <xs:annotation>
    <xs:documentation></xs:documentation>
  </xs:annotation>
</xs:element>

Exception: Oxygen snippets allows you to designate where the cursor should appear. In cases where an incomplete value appears at the same place the cursor will be set, no dots have been added. The cursor itself is the cue to fill in the rest of the information. Dots are used to indicate incomplete information in the fields that follow.

ALLCAPS

Labels written as ALLCAPS were used in places where Oxygen can be used to autofill the value if it has already been defined.

For example, the snippets for the niem-code-2 pattern provide templates for a code simple type and a code complex type with simple content (CSC). If you fill in the information for the simple type first as it appears, Oxygen will let you autofill in the name of the simple type you just created as you fill in the CSC’s base type. Autofill is quicker than editing an alternate default value set as ...CodeSimpleType.

In order to use autofill, you first need to select the current value in the field. Once fully highlighted, hit Ctrl/Cmd + Space for a list of available components and begin typing to get to the one you need.

A value without delimiters like ‘ALLCAPS’ can be selected in Oxygen from the keyboard in one Ctrl/Cmd-Shift + arrow key jump. Selecting ...CodeSimpleType would take Oxygen six jumps to fully highlight, one arrow key stroke for each dot and upper case letter. This is one of the reasons this ALLCAPS formatting convention has been selected.

Ordering

Component snippets are ordered by dependencies. The order for components in the niem-code-4 snippet is

1. Code simple type
2. Code CSC type (base type is defined in # 1)
3. Abstract element
4. Code element (type is defined in # 2; substitution group is defined in # 3)

This ordering prevents encountering required fields that have not yet been defined.

Using NIEM snippets with Oxygen

For more information on snippets in Oxygen, please see their page about Code Templates.

Import snippets

• Download the NIEM Oxygen snippets file
• In Oxygen, click on menu item Options -> Preferences…
• In the left panel sidebar, click on Editor -> Content Completion -> Code Templates
• Click the Import button near the bottom right of the panel and select the downloaded snippets file

Use a snippet

All NIEM snippets begin with niem-

• Type “niem” in an XML schema file
• Hit Ctrl/Cmd + Space
• Scroll through the drop-down list to see all snippets that begin with “niem”
• Hit “Tab” or “Enter” to load the snippet
• Fill in fields like names and definitions; adjust default values as needed

Modify a snippet

• In Oxygen, click on Options -> Preferences
• In the left panel sidebar, click Editor -> Content Completion -> Code Templates
• Scroll down and select the snippet to modify
  • The snippet will begin with “niem-“
  • NIEM snippets will appear under “XSD Editor” and/or “JSON Editor” group
• Click the “Edit” button

• Modify the snippet name, description, code, or add a keyboard shortcut.
• Notes:
  • The ${caret} variable marks the position where the cursor will appear once the snippet is loaded.

Reload snippets

• To load an updated snippets file, simply go through the original import steps again.
• Snippets with the same name and editor group will be overwritten.
• Individual snippets can be deleted or snippets can be reset by clicking the Restore Defaults button.