EDI Meta-Formats

EDI transactions are described by a set of format documents, implementation guidelines, mappings, or specs; you name it. These documents standardize the structure of each business transaction, such as an invoice or a purchase order, and the rules defined in them must be adhered to by all applications or software systems that will be processing EDI documents. This is the core tenet of EDI.

There are a few main meta-formats in use today, IBM uses SEF,  Microsoft uses XSD, EdiFabric uses .NET attributes and C# classes, etc., and a multitude of incompatible vendor-specific and proprietary scripts and languages.

The problems with ALL existing meta-formats are:

1. All meta-formats that exist today are incompatible with each other
2. None of the existing meta-formats is easily applicable to the Web or APIs

The OpenEDI Format

EDI and OpenAPI

OpenAPI or The OpenAPI Specification is a broadly adopted industry standard for describing modern APIs. It is language-agnostic, open-source, and is maintained/supported by the likes of 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal.

As of now, OpenAPI can also be used as a meta-format to describe EDI documents. This allows software developers and software systems, regardless of the programming language or the technology they rely on, to quickly adopt EDI in a standard, open and modern way. EDI documents can finally:

1. Be represented as Open API schemas in YAML, JSON, or XML format, just like any other API model
2. Translated and validated via REST APIs
3. Have their specification shared between all Web applications without the need for conversion

EDI Models

EdiNation utilized the lingua franca of the Internet and APIs, OpenAPI, to be the meta-format that standardizes EDI transactions. This allows software developers to work with EDI documents via API models, essentially, coalescing EDI formats and API models.

The transaction models represent a variety of business message types, such as invoices or purchase orders. Each model matches the rules as specified by the standard. Transaction models are used as part of X12Group's Transactions object and EdifactGroup's Transactions object.

• {
  	"Model": "EdiNation.X12.HIPAA.005010",
  	"ST": {
  		"TransactionSetIdentifierCode_01": "837",
  		"TransactionSetControlNumber_02": "0021",
  		"ImplementationConventionPreference_03": "005010X222A1"
  	},
  	"BHT_BeginningOfHierarchicalTransaction": {
  		"HierarchicalStructureCode_01": "0019",
  		"TransactionSetPurposeCode_02": "00",
  		"SubmitterTransactionIdentifier_03": "244579",
  		"TransactionSetCreationDate_04": "20061015",
  		"TransactionSetCreationTime_05": "1023",
  		"TransactionTypeCode_06": "CH"
  	},
  	"AllNM1": {
  		"Loop1000A": {
  			"NM1_SubmitterName": {
  				"EntityIdentifierCode_01": "41",
  				"EntityTypeQualifier_02": "2",
  				"ResponseContactLastorOrganizationName_03": "PREMIER BILLING SERVICE",
  				"IdentificationCodeQualifier_08": "46",
  				"ResponseContactIdentifier_09": "TGJ23"
  			},
  			"PER_SubmitterEDIContactInformation": [{
  				"ContactFunctionCode_01": "IC",
  				"ResponseContactName_02": "JERRY",
  				"CommunicationNumberQualifier_03": "TE",
  				"ResponseContactCommunicationNumber_04": "3055552222",
  				"CommunicationNumberQualifier_05": "EX",
  				"ResponseContactCommunicationNumber_06": "231"
  			}]
  	},
  	"_comment": "... rest of the contents ...",
  }

• {
  	"Model": "EdiNation.Edifact.UN.D96A",
  	"UNH": {
  		"MessageReferenceNumber_01": "000000101",
  		"MessageIdentifier_02": {
  			"MessageType_01": "ORDERS",
  			"MessageVersionNumber_02": "D",
  			"MessageReleaseNumber_03": "96A",
  			"ControllingAgencyCoded_04": "UN"
  		}
  	},
  	"BGM": {
  		"DOCUMENTMESSAGENAME_01": {
  			"Documentmessagenamecoded_01": "220"
  		},
  		"Documentmessagenumber_02": "128576",
  		"Messagefunctioncoded_03": "9"
  	},
  	"DTM": [{
  		"DATETIMEPERIOD_01": {
  			"Datetimeperiodqualifier_01": "137",
  			"Datetimeperiod_02": "20020830",
  			"Datetimeperiodformatqualifier_03": "102"
  		}
  	}],
  	"PAI": {
  		"PAYMENTINSTRUCTIONDETAILS_01": {
  			"Paymentmeanscoded_03": "42"
  		}
  	},
  	"_comment": "... rest of the contents ...",
  }

Available Models

EdiNation provides a vast and always-expanding library of EDI models. These are referred to as System models and are available to all API consumers.

System models are available for the following EDI standards:

• ASC X12
• HIPAA X12
• UN EDIFACT
• GS1 EANCOM
• HL7
• NCPDP TELCO
• NCPDP SCRIPT
• IATA EDIFACT
• VDA

Custom Models

API consumers can publish and maintain their own set of models, only visible and accessible as part of their subscription, and used in conjunction with the System models.

Custom models can be:

1. Imported from SEF files
2. Imported from EdiFabric EDI templates
3. Modified System models
4. Created from scratch following the OpenAPI EDI format

How are models used in the API

Default model resolution

When the API receives a request for translating an EDI file to JSON, it needs to identify the models that represent each transaction in the EDI file, e.g. if the EDI file contains X12 invoices and purchase orders in version 4010, then the API must find the EDI models that match X12 4010 invoices and purchase orders.

Internally, models are resolved at runtime, inferring the model from the payload content. 

• The transaction type is the value in the ST.TransactionSetIdentifierCode_01 field and the transaction version is the value in either ST.ImplementationConventionPreference_03 or GS.VersionAndRelease_8 if the former is blank.

• The transaction type is the value in the UNH.MessageIdentifier_02.MessageType_01 field and the transaction version is the value in both UNH.MessageIdentifier_02.MessageVersionNumber_02 and UNH.MessageIdentifier_02.MessageReleaseNumber_03.

The engine will try to load the corresponding model for that transaction type and version, and will then parse it accordingly, setting the Model attribute to the model identifier that was used.

In situations when no model can be found, the engine will try to parse the file using the closest model to the inferred version, and given the translation was successful, a warning will be added to the X12Interchange or the EdifactInterchange stating that the transaction was parsed using a secondary model.

Explicit model resolution

The model can be explicitly set by populating the Model attribute to override any resolution logic.

Model string

Models are specified by their identifier as a string. This attribute is optional, however, when specified, it overrides any resolution logic. 

In situations when no model can be found, the engine will not try to parse the file using other models and will return an error.

Model SDKs

All models are available for consumers as Swagger JSON Resolved. You can use the Swagger file to generate YAML or a client SDK in any language by using SwaggerHub for example.