A common error in LEXS-based XML instances is that NIEM and LEXS references point to the wrong objects.  This comes about because it is not always obvious what the endpoint of the reference should be.  XML validation and even ConTesA validation will only catch references that point to non-existant objects or objects outside the proper scope (e.g. a reference to something outside of the Package), but will not catch problems with references pointing to the wrong kind of "thing".   So it is up to those building the instances to make sure references are used correctly.

The best way to determine what a reference is supposed to point to is to look at the definition of the reference itself.  The annotation for the element definition will include details on the reference target.  For example, the NIEM SubjectInvolvedPersonAssociation includes nc:PersonReference and j:SubjectReference.  Since nc:PersonReference is in the nc namespace, you can look in the niem-core.xsd file and find the definition of PersonReference.  The ReferenceTarget is specified as PersonType.  So nc:PersonReference must point to an element of PersonType or of a type derived from PersonType.  Similarly, j:SubjectReference is defined in the jxdm.xsd file, and the ReferenceTarget is defined as SubjectType; so the reference needs to point to a Subject role rather than the underlying Person that has the Subject role.

Even without looking at each and every reference definition, there are some rules of thumb you can follow.

One point of confusion is that some associations include the word "Entity", such as EntityTelephoneNumberAssociation or EntityAttachmentLinkAssociation, leading people to believe that the association points to an Entity, rather than an object inside the Entity such as a Person.  (Part of the confusion stems from the difference between the NIEM and LEXS concepts of "Entity", which is covered in a separate FAQ.)

If you look at EntityTelephoneNumberAssociation, you can see that the reference elements do not include "Entity" in the name, which provides a hint that none of those references are intended to point to Entity objects.  You can also see that the EntityAttachmentLinkAssociation includes an EntityReference, which hints that it points to an Entity versus something inside the Entity.  You can certainly confirm details if necessary by looking at the definition of EntityReference in the lexsdigest.xsd file to see that it has a ReferenceTarget of EntityType.

So as a rule of thumb, if the reference element name (not the association name) includes the word "Entity", the reference element points to the high level entity rather than an object inside the entity.  To determine the correct target of other reference elements, you can get hints from the reference elements name (such as PersonReference or SubjectReference).  Some reference names include terms for multiple objects, such as SubjectPersonReference.  Since the reference name is "SubjectPerson" versus just Person, you have a hint that it doesn't point to a Subject role, but a Person object where the person is a subject.

When in doubt, refer to the reference element definition.

 

 

It depends on what you need to represent.

If the information has to do with metadata, such as additional information about who to contact about a data item, the information can be represented using the LEXS Domain Attribute elements, which are available in many different places in the schema. Additional information about data items as a whole may also be represented using Domain Attributes, although this should be restricted to information that is more metadata (say a title or description of the data item) rather than data (such as a nickname for a person included in the data item).

If the information is data rather than metadata, LEXS allows communities to define Structured Payloads, which provides an extension mechanism so that different communities can “extend” the Digest to incorporate richer data sets without compromising compatibility across applications.

LEXS provides a Narrative structure as a container for unstructured data associated with a data item.

LEXS and NIEM both use the term "Entity", but in different ways.

LEXS uses the term "Entity" in a general sense as defined in the dictionary, specifically as something that exists.  Early versions of LEXS defined the concept of Entity as being high level objects, such as person or drug or vehicle, that were of interest to the LEXS community.  In LEXS 3.x, entities were expanded to include roles.  So in LEXS 3.x, an Entity is a grouping of a base object (such as a person or drug or vehicle), and the base object's applicable roles (such as subject or weapon). 

NIEM uses the term "Entity" from more of a court perspective to represent people or organizations that are capable of bearing legal rights and responsibilities.

Note that LEXS defines some associations using the NIEM concept of Entity, such as EntityTelephoneNumberAssociation which defines a relationship between a NIEM Entity (i.e. a person or organization) and a telephone number.

Any change to the LEXS schemas impacts the compatibility among LEXS implementations. Even adding a single element to the LEXS schemas means that any application written for the “official” LEXS specification will have difficulties with the extended version.

An Attachment Link provides a mechanism to connect an Entity in a package to an Attachment, such as a person to a mug shot Attachment or a person physical feature to a tattoo image Attachment.

LEXS Attachments are based on the NIEM Binary element, and may contain data-related binaries such as a mug shot or fingerprint, or may contain binaries or stylesheets used by LEXS Rendering Instructions. Attachments are at the message level rather than the package level since each may be part of multiple packages, such as a message with multiple incident reports that include the same person and his mug shot.

Rendering instructions are used to display the information in a LEXS package in a specific viewing or output format for human users. A data source may want to influence the way in which the information it shares is viewed by a user at a consuming system. Using a specific rendering allows a source to present data items more intuitively to users who may not be familiar with the underlying context of the data. This is especially true when the package contains information that is specific to an agency or community and the data source is knowledgeable about how best to format the content to make it more comprehendible and user friendly. Since LEXS allows for the sharing of heterogeneous data from different sources with different contexts, user interfaces for displaying LEXS data will often need to be very generic, sacrificing intuitiveness.

The LEXS Digest concept allows data sources to encode a well-defined representation of people, places, activities, and things as well as associations among them as described previously in this document. LEXS also includes a layered mechanism for communities to define entities, roles, associations, structures and elements that are not defined in the LEXS schema. Communities that need additional data not provided in the Digest can supply that data in one or more Structured Payloads. This allows law enforcement groups or projects who are interested in information sharing to leverage LEXS as a base while developing their own specialized schemas targeted to address their own business missions.

The Structured Payload provides an extension mechanism so that different communities can “extend” the Digest to incorporate richer data sets without compromising compatibility across applications. Each Structured Payload is based on schemas created by communities outside of LEXS. Each Structured Payload includes metadata that specifies what community defined the Structured Payload schema. Consumers can use that metadata to determine if the contents can be processed or needs to be ignored.

Since Structured Payloads are based on separate schemas, Structured Payload instances must be valid as standalone instances. While the data contents of the Structured Payload may not make logical sense by itself without the contents of the Digest, the Structured Payload instance must be valid against the Structured Payload schema.

Exchange instances can include multiple Structured Payloads and a consumer might understand some and not others. Structured payloads can build upon the contents of the Digest, or even upon the contents of another Structured Payload. Some consumers may understand everything in an instance, others may understand the Digest and one Structured Payload, and still others may only understand the Digest.

The concept of the Digest is central to the power of LEXS as a framework for information sharing. A LEXS data item may represent any kind of underlying information—a warrant, an incident, a customs manifest. T he Digest is the common anchor for systems to use to handle this heterogeneous data without having to understand the specific context and meaning of the source. As long as the entities relevant to the packaged Data Item are represented in the Digest, users will be able to discover, link, map, etc. the information within.

Even though the Digest provides the common level of understanding, it does not mean that all sources have to populate all elements, or that all consumers have to use all elements; merely that at a schema level all applications understand the Digest. Implementers only need to build one module in order to produce or consume a basic set of data understandable by many. It also means that implementers do not have to develop large applications for each exchange, but rather build one that handles the basics and then additional smaller modules in order to produce or consume more complex exchanges.

LEXS defines a high level set of commonly understood, structured base objects which represent real-world objects such as person, location, or vehicle. For each base object, LEXS specifies content which provides a wide range of data representation capabilities. LEXS includes a large number of NIEM roles and associations and defines additional roles and associations needed by the LEXS community to provide detailed context for all data. These base objects, roles, and associations provide a great deal of flexibility to communities so each can define their own data items. LEXS groups these base objects and their applicable roles into entities. For example, a LEXS person entity includes a person base object and roles such as subject, witness and victim.

In LEXS, the term Package refers to a standard representation of any Data Item used for information sharing. LEXS defines two similar package structures to support Data Item publication and Data Item retrieval. Both package structures contain metadata, a Digest, and optionally multiple Structured Payloads, Rendering Instructions, and/or Attachments. When an application extracts a Data Item or database record and encodes it in a format that is compliant with the LEXS schema, the Data Item is contained within a Package structure. Conceptually, a Package represents a unit of information that is self-contained and able to convey the knowledge from the data source to the data consumer or between partner systems.

A data item is whatever the source considers a logical unit of information. For example, to an incident-based reporting system, a logical unit of information is an incident report that may contain activities, people, places, and things. To a prison system, a logical unit of information is an inmate record that may just have information about a person. The data item concept provides a single, generic container that can be used to encapsulate different types of data needed by various communities. The data item can be thought of as a collection of structured entities, attributes of these entities, relationships between these entities and unstructured textual information.

The LEXS schemas are based on NIEM and leverage many of the XML features utilized by NIEM. Some tools, and many wizards that come with various tools, are not intended for use with complex schemas or schemas that use some of the XML features used by NIEM, such as substitution groups.

No. The WSDL files included as part of the specification are provided as a convenience to developers. They can be modified for use, or used as the foundation for implementation-specific WSDLs, or ignored completely.

Yes. Structured Payloads are based on separate schemas anyway, so the use of an existing, and non “LEXS-aware”, schema is allowed. LEXS provides mechanisms for linking Digest data elements to their Structured Payload counterparts even in these cases where the Structured Payload cannot explicitly “point up” into the Digest.

Note that in the case of these non LEXS-aware Structured Payloads there may be data duplication between the Digest and the Structured Payload. However, communities using non LEXS-aware Structured Payloads must populate the Digest as fully as possible in order to promote maximum interoperability across the LEXS community.

No. However, any application intended to process the contents of a Structured Payload must be based on some well-defined specification of what to expect. Therefore it makes sense to provide that definition in a normative way using an XML schema.

Structured Payloads are based on schemas created by communities outside of LEXS, and the contents of a Structured Payload must be valid as a standalone instance against the Structured Payload schema. Therefore, in most cases, the contents of the Structured Payload must be validated separately from the contents of the rest of the LEXS message. Therefore multi-pass validation is generally required, although there may be tools that can process instances in a single pass. For validation of instances, either with or without Structured Payloads, the LEXS community provides a tool called the Conformance Testing Assistant, or ConTesA for short, which can automatically perform XML validation for entire messages, as long as the Structured Payload schema has been incorporated into ConTesA.

LEXS PD (Publication and Discovery) supports the action of publishing sharable information to a data repository. LEXS PD provides the data elements and structures required to represent the data and metadata associated with publishing data. In publishing data, a source system submits one or multiple data items in a single, one-way action to a data consumer; LEXS does not define an acknowledgment action.

LEXS SR (Search and Retrieval) represents a number of requests and corresponding responses that support data search and retrieval. LEXS SR supports requests that fall into two broad categories, data requests and service provider requests. LEXS data requests provide the mechanisms for retrieving data from partner systems and include four specific requests: text search, structured search, data item request, and attachment request. LEXS service provider requests ask for system information about partner systems including capabilities, data owners, and availability.

Each release in the 3.1 line is backward compatible with all previous releases in the 3.1 line. Therefore, any message that is compatible with LEXS 3.1.1 is compatible with LEXS 3.1.2, 3.1.3, and 3.1.4.

NIEM defines a data model that can be customized for a particular information exchange. As such, practitioners customize their NIEM subset and extension schemas for each information exchange. This results in many different information exchange schemas that are not compatible with each other. An organization that exchanges data with multiple partners must simultaneously support multiple distinct IEPDs, with the result that cost and expertise are limiting factors in the attempt to create robust, rich networks of information exchange – instead, sharing is disjoint and/or shallow.

LEXS provides an extensible framework for consistent packaging of the information, with specific placement and markings for various elements of the shared information. The LEXS specification shields both data sources and data recipients from the complexity of multiple interfaces and allows for the multipurpose use of information: for example, a data item created by a source can be consumed by multiple recipients that should be able to understand as much or as little of the data as necessary.

LEXS also simplifies the design and development since many things are already defined in the specification. For example, LEXS defines the packaging of data, such as how to ask questions or to represent “hits” from a query, as well as ancillary functions of use in a query/response paradigm, such as what capabilities a data provider supports. LEXS also provides metadata for messages, including when the message was created, who owns the data, who is submitting a query, etc.

No. While LEXS originated from law enforcement needs, it has been designed for a broad audience and is not limited to use by the law enforcement community.