How to migrate from EDI SEF (Standard Exchange Format) to OpenAPI 3, The Developer Guide

The EDI SEF Format

The Standard Exchange Format is an open standard text format, developed by the Foresight Corporation (now part of Tibco). Its purpose is to provide a machine-readable specification for EDI documents. 

This guide explains which parts of the SEF format are supported by the EDI OpenAPI format and how they are related. EdiNation uses OpenAPI for representing EDI specifications and offers a powerful converter from SEF to OpenAPI which allows proprietary specifications in the SEF format to be easily migrated to the OpenAPI format.

The official SEF Implementation Guideline is no longer publicly available, therefore we'll reference our copy of it, which is hosted on our website.

This document is for those experienced with EDI concepts and terminology.

EdiNation provides a free SEF to OpenAPI migration tool, to import and convert SEF files to OpenAPI models.

Implementation Guidelines

1. SEF

   EDI SEF Implementation Guideline

2. OpenAPI

   EDI OpenAPI Implementation Guideline

 

How the SEF to OpenAPI migration tool supports the different SEF sections

• .VER

Not used. Only version 1.61 is supported.

• .INI

Expects the fields at position 3 (version) and position 4 (agency code). The supported agencies are X and UN only.

• .PRIVATE and .PUBLIC

Not used

• .STD

Supported params are LS and RE.

• .SETS

Transactions

OpenAPI Messages Guideline

Transaction sets are defined as OpenAPI Schemas. All examples below will use YAML to represent OpenAPI items, however, both YAML and JSON are supported.

For example, the 837 P (Professional medical claim for X12 HIPAA) transaction is represented as:

The full interactive X12 HIPAA 837 P example can be found here.

Multiple transactions can be defined as  Schema objects, the same as in SEF files. Loops (groups), segments, and complex data elements are represented as separate Schema objects only once in the YAML and are then referenced as types in each object property using the $ref: notation.

OpenAPI Schema Objects

There are no distinct dictionary and implementation guideline interpretations, therefore, attributes like SEF's ". not used", "$ recommended", "- not recommended" and "& dependent" are not supported on neither segment nor loop level.

All class and property names are open to change and can be renamed, for example, to match a coding convention. The same applies to the casing.

All transaction objects must provide the following extensions to identify the transaction:

x-edination-message-standard - the transaction standard, X12 or EDIFACT, derived from the .INI section

x-edination-message-version - the transaction version, derived from the .INI section

x-edination-message-id - the transaction name or number

Segments

Segments in sets are represented as properties referencing a segment object. In SEF, the reference is by the segment id and mask number, whereas in OpenAPI is using the $ref: keyword, pointing to the referenced object.

OpenAPI Schema Objects

Segment requirement in SEF is represented using the standard designator and can include: M, O, F, or C. If omitted, the default is O for optional (X12 or TDCC) or C for conditional (EDIFACT). In OpenAPI, the requirement is achieved using the "required keyword". When attribute "! must be used" is present, the segment is marked as required even if it's not marked with the M attribute.

Segment maximum is represented by setting the corresponding property as an array, and the number of repetitions using the minItems and maxItems keywords. SEF's >1 notation, is converted to maxItems = 99999.

Loops (Groups)

Loops are represented just like any other object:

 

with extension:

x-edination-loop-id - the loop name or id. This can be any value.

Loop requirement and loop maximum are represented exactly that same as for segments, using the "required keyword" and "arrays".

Tables

Tables are not supported because they serve no purpose.

Ordinal Numbers

Ordinal numbers are not required because their purpose in SEF is to uniquely identify a segment or a loop within the transaction. In OpenAPI this is achieved by the name of the property referencing the Schema object - it needs to be unique. 

Inserting new properties in OpenAPI is straightforward. For example, if we need to insert a new segment, NTE, between CUR and REF and with the same name as an already existing segment, in SEF an ordinal number is required. In OpenAPI we only need to ensure that the new property name is unique.

Position Numbers

Position (or sequence) numbers reflect the position numbers of the X12 or EDIFACT standards. Unlike ordinal numbers, they have no other function within SEF. Position numbers are not required and the ordering of segments and loops is achieved by listing the properties in the intended order, from top to bottom.

In OpenAPI, every property is "in a position", e.g. segments and loops alike. Re-ordering means that the properties can simply be rearranged.

The concept of position number reuse and segment variations (when having a negative position or +0/-0 position) is achieved by:

- having an "unordered" loop object, which is the same as a loop object but without the x-edination-loop-id extension. Usually, it's prefixed with All, a notation left from XSD.

- having all variations of a segment or loop as properties in that "unordered" loop object 

The SEF migration tool supports LS and the new EDIFACT standards to correctly interpret the position numbers.

Summary of Symbols used in .SETS

[ ]  property name

{ } property name

+ or - position is the order of properties from top to bottom

: maxItems keyword

^ N/A

* new property with a unique name, referencing a new object

@ N/A

. N/A

! required keyword

$ N/A

- N/A

& N/A

M, O, F, or C required keyword

• .SEGS

OpenAPI Segments Guideline

Segments are defined as OpenAPI Schema objects. The same way as transactions, loops, and composite elements. Each segment must have the x-edination-segment-id extension, with the value being the exact segment ID as per the standard.

For example, in the 837 P (Professional medical claim for X12 HIPAA) transaction, a REF segment is represented as:

The full interactive X12 HIPAA 837 P example can be found here.

Segments can contain repeatable elements and composite elements. These are represented as properties of any name and the following rules:

• Element must have the x-edination-element-id extension, with the value being the exact element ID as per the standard.
• Requirement is implemented with the "required" keyword.
• Count or repetition is implemented as a property of "array" type. Element types must be of type string. Composite types must use the $ref: keyword pointing to the composite object. The maximum number of repetitions is set with the "maxItems" keyword.
• Element types, that are not EDI codes, must all be strings. The actual data type is represented with the "format" keyword. The supported X12 and EDIFACT data types can be found here.
• Minimum and maximum lengths are represented with the "minLength" and "maxLength" keywords.

Ordinal Numbers

Ordinal and position numbers are not supported because each segment is identified by its unique property name and reference to the actual type. The order (top to bottom) in which properties are arranged controls their position in the segment.

User Requirements

There are no distinct dictionary and implementation guideline interpretations, therefore, attributes like SEF's ". not used", "$ recommended", "- not recommended" and "& dependent" are not supported.

When attribute "! must be used" is present, the element/composite is marked as required even if it's not marked with the M attribute.

Repeating Patterns of Elements

Repeating patterns are not supported and all element/composite properties must be specified according to the specification order and with unique names.

Element Repeat Counts

Element repeat counts are supported by marking the property of "array" type, with the items of type "string", see Element_04 in the last example. The same convention applies to composite elements.

Syntax Rules or Dependency Notes

Syntax rules are supported for X12 and HIPAA only, by using the x-edination-syntax extension. It's an array type and allows for multi syntax notes.

The format of each array item must be:

{condition designator}{start position}[other positions]{end position}

{start position}, {end position} and all other positions in-between must be two-digit numeric values, 0 to 9 must be padded with a leading zero.

{condition designator} must be any of the following values:

• P- Paired
• R- Required
• E- Exclusion
• C- Conditional
• L- List Conditional

Example:

'Masks' or Alternate Variations

Segment and composite masks are supported using separate objects for the dictionary segment and any variant. The following rules must be observed:

• Segment variants are represented as different segment objects with the same segment ID set as a value in the x-edination-segment-id extension.
• All property names and property order across all segment variants must be the same.
• Referring to a variant of a segment is the same as referring to any other object, by using the $ref: keyword.

Segment variants can amend the following:

• Element/composite repeat count
• Element min or max length
• The composite reference, if it points to a variant of the original composite
• The EDI code type
• The requirement, optional or required
• The syntax rules

 

Summary of Symbols used in Segment Masks

Segment masks describe elements in segments at a particular location in the transaction set or message.

, (comma) multiple segment variations are supported

. (dot) N/A

# N/A

@ N/A

$ N/A

- N/A

& N/A

+ N/A

[min:max:repeat] minLength, maxLength, maxItems keywords

M required keyword

O required keyword

C required keyword

X required keyword

*n supported using a reference to a different object

 

Summary of Symbols used in .SEGS (Exclusive of Masks)

These symbols describe elements in a dictionary segment.

@ supported by unique property names

[ ] property

M required keyword

C required keyword

O required keyword

X required keyword

; minLength and maxLength keywords

: minLength and maxLength keywords

{ } not supported, all elements/composites must be included and have unique names

+ supported using the x-edination-syntax extension

, supported as new objects

. N/A

! required keyword

$ N/A

- N/A

& N/A

*n supported using a reference to a different object

• .COMS

Composite elements are defined as OpenAPI Schema objects. The same way as transactions, loops, and segments. Each composite element must have the x-edination-composite-id extension, with the value being the composite element ID or any other value.

For example, in the 837 P (Professional medical claim for X12 HIPAA) transaction, a C040 dictionary variant is represented as:

The full interactive X12 HIPAA 837 P example can be found here.

Composite elements can contain repeatable elements only. These are represented as properties of any name and the following rules:

• Element must have the x-edination-element-id extension, with the value being the exact element ID as per the standard.
• Requirement is implemented with the "required" keyword.
• Count or repetition is implemented as a property of "array" type. Element types must be of type string. The maximum number of repetitions is set with the "maxItems" keyword.
• Element types, that are not EDI codes, must all be strings. The actual data type is represented with the "format" keyword. The supported X12 and EDIFACT data types can be found here.
• Minimum and maximum lengths are represented with the "minLength" and "maxLength" keywords.

Ordinal numbers, User Requirements, Repeating Patterns, Element Repeat Counts, Syntax Rules, and Masks are represented in the same way as in segments, so see the .SEGS section.

There are no sub-element repeats within a composite element.

 

Summary of Symbols used in Composite Masks

, (comma) multiple composite variations are supported

. (dot) N/A

# N/A

@ N/A

$ N/A

- N/A

& N/A

+ N/A

[min:max] minLength, maxLength keywords

M required keyword

O required keyword

C required keyword

X required keyword

 

Summary of Symbols used in .COMS (Outside of Masks)

@ supported by unique property names

[ ] property

M required keyword

C required keyword

O required keyword

X required keyword

; minLength and maxLength keywords

: minLength and maxLength keywords

{ } not supported, all elements must be included and have unique names

+ supported using the x-edination-syntax extension

, supported as new objects

. N/A

! required keyword

$ N/A

- N/A

& N/A

• .ELMS

OpenAPI Data Elements.

Elements are represented as properties in segments or composite elements and not as separate objects. The minimum and maximum length defined in their parent object take precedence over what is defined in the ELMS section. The names of the properties are constructed out of the description defined in the ELMS, TEXT section.

The EDI codes, defined with an ID type, are looked up from the .CODES section (see below). The minimum and maximum length are defined using the minLength and maxLength keywords.

The following data types are supported (in addition to EDI codes/ID type):

1. X12_AN - X12 alphanumeric

2. X12_NX - X12 numeric with implied decimal, X can be any between 0 and 7

3. X12_DT - X12 date

4. X12_TM - X12 time

5. X12_RX - X12 decimal, X is digits to the right of the decimal and can be any between 0 and 7

6. EDIFACT_AN - EDIFACT alphanumeric

7. EDIFACT_A - EDIFACT alphabetic

8. EDIFACT_N - EDIFACT numeric

The type is specified using the "format" keyword. 

• .CODES

Data elements with type ID are defined as OpenAPI "enums". 

The ID types are referenced withing data elements using the $ref: keyword within an allOf: keyword:

Both dictionary and implementation guideline implementations are supported. When an implementation definition differs from the dictionary, a new enum is created for that implementation set. For all references to that implementation set, a new composite to segment is created. 

Code 

649=2:9,10,11%[-4,5]+810/5///3[#1,5]+810/3///7-4+810/6///17+875/32///7-4

will generate 3 separate enums, the first always is the dictionary and the implementations are postfixed with 1,2, etc. to reflect the correct implementation number. All occurrences in the set to 649 will reference the first enum, the dictionary. All additional references to implementations will reference the relevant implementation. 

The following codes constructions are supported (at all levels, transaction, segment and composite):

Multiple Code Sets for One Element

Same Code Set Used in Multiple Places 

Code Set Entirely from Dictionary Codes

 Code Set Contains No Codes from Dictionary

Code Set Contains all Dictionary Codes

Code Set for Element that has No Dictionary Codes

Code Set Contains All Codes Except Specified Ones

Referring Back to Previous Code Sets

All Codes are Unused

Codes with Partitions

Partitions are represented in the same way as enums, within the same enum. The partition values are postfixed with the pipe symbol | . The following is a partition enum:

and the allowed values are A, B, A4, A5, B4, and B5. Partial codes validate against either the first partition or a combination of any the first partition with any of the second partition. Only two partitions are allowed and the values of the second partition alone are not valid.

Codes that Contain Hyphens

Not supported because TRADACOMS is not yet supported.

Code Sets in Composites

A new composite will be created to refer to the two implementations, however, all other references to that composite will refer to the dictionary.

Code Sets Attached in Dictionary

This is by far the most complex representation as it might include changes in codes on multiple intersecting levels. It is supported by creating a new object (codes enum, composite, and segment) to accommodate the required structure.

Empty Code Sets

Unattached Code Sets

 

Summary of Symbols used in .CODES

n:n Supported. A range of codes in the dictionary: 05:15 means 5 through 15. The beginning and ending code must have the same length. Example: 05:15 is good because both numbers have 2 digits. A:Z is good because both have the same number of letters. 5:15 is not good because 5 has one digit, while 15 has two digits. A:ZZ is not good because A has one character while ZZ has two. Combinations of letters and numbers are also supported up to a maximum of 3 codes.

% Supported. The end of the list of dictionary codes.

[ ] Supported. Marks the beginning and end of a code set in the implementation guidelines.

( ) Supported. Surrounds the code set ordinal number.

{ } Supported. Surrounds codes that are not in the dictionary.

+ Supported. Appears after the code set and immediately before the location of the transaction set or message/segment/element where it is used.

/ Supported. Separates the parts of the location where the code set is used. 

- (in location area) Supported. Ordinal numbers are counted in order to maintain correct internal references.  Appears between the ordinal number of the composite within the segment, and the ordinal number of the subelement within the composite. Example: 4-1 means the composite with ordinal number 4 within the segment, and the subelement with ordinal number 1 within that composite.

- (inside square bracket area) Supported. Code set includes all codes in the dictionary or in referred-to code set except the ones listed after the minus sign. 

- (inside square bracket area) Not supported.

* Supported. Indicates that a code set uses all dictionary code values.

#n Supported. Refers back to code set n.

| Supported. A vertical bar separates the partitions in partitioned codes.

• .VALREFS and .VALLISTS Sections

Not supported.

• .OBJVARS Section for Variable Names

Not supported.

• .SEMREFS Section for Semantic Rules

Not supported.

• .TEXT,SETS

Not supported.

• .TEXT,SEGS

Not supported.

• .TEXT,COMS

Not supported.

• .TEXT,ELMS

Text from elements is used to generate the names of data elements. It uses the reference at position 0 in the TEXT,ELEMS and removed all spaces an special characters, leaving only alphanumeric characters. All property names are also postfixed with the correct position for easier location.

• All other sections, not listed here

Not supported.