niem/niem.github.io

NIEM is a community-driven, standards-based approach to exchanging information.

NIEM.github.io

Source repo for the website NIEM.Github.io.

The website runs under Github pages, which runs Jekyll.

The main repository for this repo is https://github.com/niem/niem.github.io/.

Dependencies

• Ruby
  • Jekyll
  • Bundler
• Graphviz

Installation

Run the following from a Unix-like command line:

$ git clone https://github.com/niem/niem.github.io.git
$ cd niem.github.io
$ git submodule init
$ git submodule update
$ bundle install
$ bundle exec jekyll serve

Point your browser at http://127.0.0.1:4000 to view the site.

Editing

Edits and updates to the page are welcome. It would be very helpful if you would:

1. Please fetch and merge in the master branch.
2. Please rebase any series of commits down to a single commit to be merged in (run "rebase -i master" and squash commits to a single commit). This is easiest if you work in a dev branch, not the master branch.
3. Please submit the commit as a Github pull request.

niem.github.io's Issues

SuperHero Association

Comparing SuperHeroBadGuyAssociation.xml and SuperHeroAssociation.xsd
I noticed BadGuy and SuperHero objects are given nc:PersonType in the extension file, but in the sample xml the BadGuy object is missing PersonNameType.

SuperHero and BadGuy should have the same properties.

NIEM-UML 3.0 Status?

I am an new active developer in NIEM UML. I am having a hard time finding people working with the same tool/plugin. There isn't a lot of support or resources or even examples for such tool. I feel like I am just throwing darts into the dark. I am currently working on the Eclipse environment, but I am not sure if that is the adequate environment for NIEM UML. I'd like to cooperate with other developers using NIEM-UML , I've been done some progress on my own and I'd like to share.

-Questions:
What is the status for the 3.0 version?
Also, what is the relationship between these repositories:
https://github.com/niem/niem-uml
https://github.com/info-sharing-environment/NIEM-Modeling-Tool

Shrink button doesn't work on accordions on the landing page

Opening an accordion on the landing page shrinks the previously opened accordion, but the shrink button itself does not seem to work.

ConTesA alternative

Hello I am a NIEM developer with a background on web app development. After doing research on ways to validate NIEM schemas and giving up on finding true solutions. I decided I'd give a shot to create my own NIEM Schema validator.

The idea is to create a web app that would scrape the XML and check for conformance. I am somewhat familiar with the conformance rules (documentation for every component, only one annotation required, name formatting, etc).

ConTesA is not very friendly to read and the rules aren't very self explanatory, I'd like to propose a more simple tool that would check for the essential rules and most critical ones. Where can I learn more about conformance for NIEM Schemas? The true intention of this tool is to be universal and only perform a high level validation just to make sure the schema is not missing any essential elements.

Add CTAS to Reference / Specifications

Add the Conformance Targets Attribute Specification (CTAS) to Reference / Specifications.

Landing page styling broken on forked repos

The styling is broken on the landing page for all forks of https://niem.github.io.

Add modeling tutorial

Add content demonstrating how to model local extensions, going from a mapping document to schemas.

Category tagging

Figure out how to implement tagging (with yaml frontmatter) in jekyll and GitHub pages to make related information easy to find.

Fix styling of lists to indent lists

Lists on the site look like this:

But should look something like this:

blockquote font is probably too big

I haven't seen blockquotes used anywhere else on the site, but using them for the JSON page yields interesting results. The font for blockquote is distinctly larger than the regular text font, and looks weird as a result.

Source code for the page looks like:

JSON is defined by RFC 4627:

JavaScript Object Notation (JSON) is a lightweight, text-based,
language-independent data interchange format. JSON defines a small set of
formatting rules for the portable representation of structured data.

The NIEM Technical Architecture Committee (NTAC) is in the process of developing
guidelines and specifications supporting the use of JSON with NIEM.

Update Normative Rules

• Move reference/normative-rules to reference/specifications/normative-rules.
• Archive existing page to /3.0.
• Update NDR rules in main page to 4.0.

Refactor XML Catalog information to Reference / Artifacts

XML catalog information is repeated in multiple places throughout the site. Refactor and define once in Reference / Artifacts and reference new section if needed.

Add default table style

Tables do not currently have a default style.

Would like to have tables default with the following classes: table table-hover table-striped table-bordered

Where are the schemas?!

Apologies if I'm missing the obvious, but where is the latest release?

I see a download button on your website, but as a developer that's no good!

Can you publish an npm package? Put the latest release in a git repo here on Github? How do I write flexible programmatic interfaces against your standards when I have to manually download or screen scrape to get the latest release?

Eliminate discussion of converting to RDF/XML or Turtle

In JSON Guidance §1.4, eliminate discussion of converting to RDF/XML or turtle.

JSON-LD is a fully-fledged RDF representation.

CSV seems to be out of date in the downloads

Several attributes seem to be incorrect or out of date.

For example, in the edxl-cap.xsd document, the imported namespace for 'cap' is version 1.1, and in the reference documents the path is correct 'external/cap/1.1', however in the .xslx tab Namespace, cap has a Version Release Number of 1.0, making it impossible to programmatically access the correct external schema.

Add info that governance determines where components are located

Make sure there is information that describes how stewardship and governance determine whether components should be located in Core or in one of the domains.

Update links to NDR, code lists spec to latest version

on page http://niem.github.io/iepd-starter-kit/conformance/, regarding links to NDR & Code list spec:

• for now, update links to point to latest document version.
• Later, redirect links to point to a landing page on this site, which should point to the all relevant document versions.

Cardinality of json crash example is wrong

You have j:Crash as an array, but you should have j:CrashVehicle as an array.

In http://niem.github.io/json/tutorial/

Non-Normative Guidance in Using NIEM with JSON

I fail to understand the need for the level of complexity which appears to be in the current document. Why are we treating the simple task of finding a way to allow JSON developers to do NIEM exchanges with JSON as if we must construct a JSON interface which contains all of the NIEM compliance constructs found in NIEM XML? It is not as if the JSON developers are going to actually want to know this information. If that were the case, then they would have learned how to do it in XML. The cold hard fact is that the reason why JSON developers want us to allow them to submit with JSON is EXACTLY because they do NOT want to have to learn all of the NIEM constructs and rules. As such, we should simply give them a JSON Schema and sample JSON document, and then let them do their job!

I already have a working example of how this can be done in which we used the Nibrs IEPD 4.0 exchange. RIGHT NOW we have a fully functional exchange which can take an XML or a JSON document and import it into the exact same SQL database. I have included 3 files below which we use in our process:

This is a Nibrs XML document:
nibrs.xml.txt
This is a JSON Schema definition which matches our Nibrs exchange:
Json Schema.txt
This is an actual JSON exchange document:
Json File.json.txt

I see no reason to go to the lengths in which this document outlines in order to accomplish the mission at hand. We will simply be wasting a ton of time, energy, and money for something that they JSON community WILL NOT care about in the end. All they want is a way to keep them from having to learn XML and NIEM...

Expanded Term Definitions as NIEM Types

Making this a stand-alone issue.

Instead of generating templates with null values, the JSON guidance could include using expanded term definitions as NIEM types.

For example, a nc:PersonType would be represented:

{
  @context:{
    "nc": "http://release.niem.gov/niem/niem-core/3.0/#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
     "nc:Person":{
         "@id":"https://release.niem.gov/niem/niem-core/3.0/element/Person",
         "@type":"nc:PersonType"
      },     
     "nc:PersonName":
     {
       "@id": "https://release.niem.gov/niem/niem-core/3.0/element/PersonName",
       "@type": "nc:PersonNameType"
     },

     ...
  }
}

This would be in keeping with IRI expansion within a context.

NIEM Movement Function Request - Import Schema

Movement is working pretty nicely for us. Would very much like to see an import utility for previously generated schemas (or alternatively a "save schema" option which can bring back schema structure).

Right now, we do this by exporting the additional bits and doing a manual copy and paste from the old schema into the new one.

The regular font is too small

Would like to see the regular font size increased for better readability.

Extract snippets from master example files

Easier to maintain and validate one master set of XML schemas, instances, JSON files, etc. than it is to have bits and piece scattered across different pages. Look at how this is already being done for the NDR and JSON work.

Improving homepage to "unbury" destinations

This is a quick mockup of how I'd suggest unburying destinations on the homepage. Clearly a lot of things can be laid out or customized further, but going down this initial path would be the correct methodology in my opinion to target visitors to the right places inside of the niem.github.io website.

Note the "rdf:value"-ization of instances is part of conformance validation

The process of going from a literal to object representation for JSON-LD will be part of the testing process for conformance. rdf:value entries will be added to convert up to RDFS-valid LD

JSON guidance on non-namespaced elements or attributes.

Section 3.2 says:

ASSUMPTIONS: All of the IEP’s namespace declarations are at or above the IEP’s root element (if there is an envelope around the IEP’s root element). There is no content using the default (no namespace prefix) namespace.

I would like to think about what can be done about that assumption. Embedding external XML namespaces into NIEM XML isn't unheard of. And I don't like leaving that field wide open.

Several lines hidden when following an anchor link

Following a link to an anchor can be confusing. The first several lines that should appear are hidden by the menu bar across the top.

Steps to recreate:

• Go to http://niem.github.io/json/guidance/
• Click on the link "Introduction" under the "Content" section
• Expected behavior: should see section header "1. Introduction"
• Actual behavior:
  • Section header is hidden under the menu bar.
  • First fully visible line is the first sentence from the second paragraph of that section.

Style of <code> blocks is not good

The style of <code> blocks should be improved:

1. the font doesn't say "code" to the reader; a typewriter-style font is traditional. Something like Courier New would be clearer.
2. they are styled as red with pink background. Regular text colors would be better.

Broken DMG link on the Domain Modeler home page

On the Domain Modeler home page, http://niem.github.io/training/domain-modeler/, there is a link to the domain-modeling-guide, but the link takes you to:

http://niem.github.io/tips-and-tricks/domain-modeling-guide/,

when it should take you to:

http://niem.github.io/reference/domain-modeling-guide/

Incorrect values in example genericode file

I note in your one sample genericode file the incorrect expression of "short name" values. Per genericode rule R39, and repeated where short name values are discussed, such a value must not contain white-space:

http://docs.oasis-open.org/codelist/cs-genericode-1.0/doc/oasis-code-list-representation-genericode.html#_Toc190622861

It is also noted in the schema:

  <xsd:complexType name="ShortName">
    <xsd:annotation>
      <xsd:documentation>A short name without whitespace that is suitable for use in generating names for software artifacts.</xsd:documentation>
      <xsd:documentation><rule:text id="R39" category="document">Must not contain whitespace characters.</rule:text></xsd:documentation>
    </xsd:annotation>

Looking in make-model.gc I note a number of column short name values have embedded spaces.

I hope this helps.

G. Ken Holman
Chair, OASIS Code List Representation Technical Committee
http://www.oasis-open.org/committees/codelist

Consider new look for landing page

Resources available for updating the look through the end of the calendar year

The sample schema provided is not usable

This schema uses json pointers to reference instance properties inside the definitions. Definitions are meant for 'schema reuse', and should be independent of the document in which they are embedded. Having references back to properties undermines the entire concept of reuse, and makes parsing dependent on the schema instance.

Training tracks

There will be multiple kinds of users looking at NIEM training.

We would like to be able to create some specialized training tracks so that...

• a person looking to understand what NIEM is can easily navigate through the overview pages
• a person looking to understand how to model NIEM with XML can easily navigate through the overview, modeling, and XML pages
• a person looking to understand how to model NIEM with JSON can easily navigate through the overview, modeling, and JSON pages
• etc

We would like to be able to create a couple of different training tracks that mix and match pages so that we can present only the pages that are relevant to the user. And we would like to not have to duplicate content. For example, training track A might be pages 1, 5, and 8. Training track B might be pages 1, 2, 5, 8, and 10.

At a basic level, this could be implemented by creating a page for each training track containing a list of links to all of the pages that are relevant. Would like to come up with an easier way for a user to navigate through their track - a way to be able to walk through the designated material via something like "next" buttons. But that "next" button would depend on which track you are on.

Add NDR to Reference / Specifications

Make sure 3.0 training is accessible

Check if training log in works, and/or if pdfs can be posted without a log in.

Identify how to omit pages from the side bar

for the simple iepd tutorial, in response to user feedback, we've stood up 3 quizzes ("knowledge checks"), which appear on separate pages.

These quzzes are appearing on the navigation sidebar. We would like to be able to omit these from the sidebar.

externalize context from JSON instances

In JSON guidance, break instances up so that JSON-LD context is separate from the LD payload data. We don't want it to appear that instances must carry context.

Add note for meaningful code values

Add a note recommending using meaningful code values rather than auto-incrementing integerse when creating a new code set.

Update Subset Schema in Reference / Artifacts

• Add a bigger intro to explain the value of a subset
• Add information about how subsets relate to IEPDs
• Refactor subset information from Reference / Tools / SSGT
• Rearranged and simplified list of possible subset operations for better readability
• Removed links to non-existent sub-pages

update to graphic needed

update needed in section: http://niem.github.io/json/whatis/#model

The flower petal image used was retired with the 4.0 release, when the CFYS namespace was removed and agriculture added.

You should be able to copy the current image found at https://www.niem.gov/about-niem

Refactor Reference and fill in missing sections

Refactor some of the pages in Reference to better group the information and fill in gaps.

Specifications:

• #65 - Add CTAS
• #68 - Add NDR and refactor related pages
• #69 - Update and refactor Normative Rules to Reference / Specifications
• #70 - Move Conformance to Reference / Specifications and update
• #74 - Add MPD Spec
• #77 - Add HLVA

Artifacts:

• #66 - Refactor XML Catalog to Reference / Artifacts
• #67 - Update Subset Schema
• #71 - Update Extension Schemas
• #72 - Move Releases to Reference / Artifacts / Releases
• #73 - Refactor Core Supplements to Reference / Artifacts / Releases
• #75 - Move Reference / IEPD to Reference / Artifacts
• #76 - Add Domain Update

Tools:

• #78 - Update ConTesA

Recommend use of @context & URI in JSON-LD instances

The NTAC JSON working group requests that it be RECOMMENDED that a JSON-LD instance has an @context attribute, with a value of a URI for the applicable context.

Feedback on 3.0-based training

Feedback from MCTSSA was provided on the 3.0-based training. Should be reviewed for comments that still apply to the updated training.

Old NIEM Training - General Comments.docx

Header fonts are too large

Some of the pages use H2 or H3 as the initial header to avoid the large font.

Syntax highlighting is missing on code blocks

Code snippets that are defined in code blocks with triple-backticks and a language name should have syntax highlighting, like the example below:

<xs:schema>
  <xs:element name="Person"/>
</xs:schema>

Syntax highlighting is not working in the website. See the code block at http://niem.github.io/json/guidance/#namespaces-and-json-ld-context for an example.

Add links to domain workspaces

Suggestion was provided to add a place on the website to link out to domain repos / workspaces for the development and management of their content.

Make it clearer that the IEPD lifecycle is iterative

Comment from the NBAC face-to-face meeting was that it should be clearer that the IEPD lifecycle is an iterative process, allowing for continual improvements.

Sidebar navigation panel

Currently, the sidebar navigation panel only reflects the first-level sub-directories.

Would like for this nav panel to reflect the current subdirectory.

May need to include a way to explicitly exclude certain subdirectories from the nav panel.

GRANT FEEDBACK & ISSUES

please leave your grants feedback here.