IsyLab Exchange Format - CIPP Laboratory Exchange Made Easy

IsyLab is a digital exchange format for final laboratory test results in the context of Cured-In-Place-Pipe installations.

The exchange format was created to standardize and streamline the communication of laboratory testing data in the context of Cured-In-Place-Pipe (CIPP) installations. Historically, laboratory parameters were exchanged via unstandardized formats or paper reports, causing slow processes and manual data entry errors. IsyLab is intended to eliminate manual transcription with a generic format. The goal is improved exchange efficiency, reduced transcription errors, and machine-checkable structural correctness.

1. Scope and design goals

IsyLab focuses strictly on the efficient and structured transmission of actionable laboratory data. It exchanges final result values, final evaluations, relevant setup conditions, specimen references, and procedure-level summary evaluations.

The format is specifically designed for automated exchange between laboratory software and the leading CIPP management software Mate.

IsyLab is designed to:

• Reduce manual transcription of final CIPP laboratory results.
• Provide a stable Procedure -> Specimen -> Test -> Parameter hierarchy.
• Keep result values, units, limits, and evaluations close together.
• Support XML and JSON exchange.
• Support strict structural validation through XSD and JSON Schema.
• Use UCUM unit codes for machine-readable units.
• Allow flexible exchange levels (e.g., final result exchange without mandatory specimen or test details).
• Support the linking of external documents, such as test curves or photographic evidence, at various hierarchy levels.

IsyLab currently does not implement (Potential future scope):

• Transmission of raw measurement data and continuous plots (e.g., raw evaluation curves).
• Detailed models for measurement uncertainty.
• Complete calculation histories and intermediate mathematical steps.
• Extended audit trails for full data provenance tracking.

IsyLab is explicitly not designed to:

• Fully replace visually formatted, human-readable laboratory reports.
• Act as an internal database for laboratory resource management (e.g., device calibration, equipment metadata, or staff assignment).
• Guarantee the scientific correctness of the exported laboratory values (the exporting system remains responsible for data accuracy).

2. Format structure

2.1 Root structure

2.1.1 XML root

<IsyLab version="1.0">
    <Header>
        ...
    </Header>
    <Procedures>
        ...
    </Procedures>
</IsyLab>

2.1.2 JSON root

{
    "type": "IsyLab",
    "version": "1.0",
    "header": {},
    "procedures": []
}

2.2 Header

The header contains export metadata.

2.2.1 XML

<Header>
    <ExportSoftware>ExampleLabSoftware Pro V2.5.1</ExportSoftware>
    <GenerationTime>2024-10-26T14:32:00Z</GenerationTime>
</Header>

2.2.2 JSON

"header": {
    "exportSoftware": "ExampleLabSoftware Pro V2.5.1",
    "generationTime": "2024-10-26T14:32:00Z"
}

2.2.3 Fields

Field	Required	Type	Description
ExportSoftware / exportSoftware	Yes	Text	Name and version of the exporting software.
GenerationTime / generationTime	Yes	Date-time	UTC generation timestamp.

2.3 Procedure

A procedure represents one Mate-linked testing procedure.

2.3.1 XML

<Procedure mateId="00001X1">
    ...
</Procedure>

2.3.2 JSON

{
    "mateId": "00001X1"
}

2.3.3 Fields

Field	Required	Type	Description
mateId	Yes	Text	Mate installation identifier.
ProcedureData / procedureData	No	Object	Context metadata.
Specimens / specimens	No	Array	Extracted specimens and test details.
FinalResult / finalResult	Yes	Object	Procedure-level final evaluation.
Documents / documents	No	Array	Linked documents.

A procedure may contain only a final result and no specimen data.

2.4 Procedure data

Procedure data contains lightweight context fields.

2.4.1 Fields

Field	Required	Type	Description
Laboratory / laboratory	No	Text	Laboratory name.
Client / client	No	Text	Client name.
ReportNumber / reportNumber	No	Text	Official laboratory report reference.

2.5 Specimen

A specimen represents a physically extracted sample.

2.5.1 Fields

Field	Required	Type	Description
id	Yes	Text	Specimen identifier within the procedure.
ExtractionDate / extractionDate	Yes	Date	Extraction date.
ExtractionTime / extractionTime	No	Time	Extraction time in UTC.
ExtractionLocation / extractionLocation	Yes	Object	Location of extraction.
ExtractionDistance / extractionDistance	No	Object	Longitudinal extraction distance from start node.
ExtractionClockPosition / extractionClockPosition	No	Clock position	Radial pipe position from 01:00 through 12:59.
SampleOrientation / sampleOrientation	No	Text enum	Orientation of the cut sample. Allowed values: longitudinal, circumferential.
Tests / tests	No	Array	Tests performed on the specimen.
Documents / documents	No	Array	Linked documents.

2.6 Extraction location

2.6.1 Fields

Field	Required	Type	Allowed values	Description
Type / type	Yes	Text	Section, Manhole	Type of referenced structure.
Name / name	Yes	Text	Any non-empty text	Structure identifier.

2.7 Test

A test represents one final laboratory routine result set for one specimen.

2.7.1 Fields

Field	Required	Type	Description
id	Yes	Text	Unique test identifier within the procedure.
name	Yes	Text	Test identifier.
Standard / standard	Yes	Text	Applied standard or method designation.
TestDate / testDate	Yes	Date	Test date.
TestTime / testTime	No	Time	Test time in UTC.
Conditions / conditions	No	Array	Setup conditions.
Parameters / parameters	Yes	Array	Final result parameters.
Documents / documents	No	Array	Linked documents.

2.8 Condition

A condition is a setup or test environment value. Conditions are informational inputs and do not carry evaluations.

2.8.1 Fields

Field	Required	Type	Description
name	Yes	Text	Condition identifier.
NumericValue / value	Yes	Number	Numeric condition value.
Unit / unit	Yes	UCUM code	UCUM unit code.

2.9 Parameter

A parameter is the most granular final result payload.

2.9.1 Fields

A parameter must contain exactly one final result value.

In XML, the value is represented by one of the typed value elements:

• NumericValue
• TextValue

In JSON, the value is represented by the single value property using the native JSON type.

Field	Required	Type	Description
id	Yes	Text	Unique parameter identifier within the procedure.
name	Yes	Text	Parameter identifier.
NumericValue / value	One value is required	Number	Numeric final result value.
TextValue / value	One value is required	Text	Textual final result value.
Unit / unit	Required for numeric values only	UCUM code	Unit for numeric values. Omitted for qualitative values.
Limit / limit	No	Object	Limit definition for evaluation.
Evaluation / evaluation	Yes	Evaluation enum	Evaluation of this parameter.
Documents / documents	No	Array	Linked documents.

XML value rules:

• NumericValue must be used for quantitative numeric values.
• TextValue must be used for textual qualitative values.
• Exactly one of NumericValue orTextValue must be present.
• Unit is required when NumericValue is used.
• Unit must be omitted when TextValue is used.

JSON value rules:

• Numeric values must be JSON numbers.
• Text values must be JSON strings.
• unit is required when value is a number.
• unit must be omitted when value is a string.

2.9.2 Evaluation values

Allowed values:

pass
fail
not_evaluated

2.10 Limit

A limit defines how a parameter value is evaluated.

2.10.1 Single-value operators

Allowed single-value operators:

greater_than
greater_or_equal
less_than
less_or_equal
equal
not_equal

Example XML:

<Limit>
    <Operator>greater_or_equal</Operator>
    <NumericValue>10000.0</NumericValue>
    <Unit>MPa</Unit>
</Limit>

Example JSON:

"limit": {
    "operator": "greater_or_equal",
    "value": 10000.0,
    "unit": "MPa"
}

2.10.2 Range operators

Allowed range operators:

between
outside

Example XML:

<Limit>
    <Operator>between</Operator>
    <MinNumericValue>3.0</MinNumericValue>
    <MaxNumericValue>5.0</MaxNumericValue>
    <Unit>mm</Unit>
</Limit>

Example JSON:

"limit": {
    "operator": "between",
    "minNumericValue": 3.0,
    "maxNumericValue": 5.0,
    "unit": "mm"
}

2.10.3 One-of operator

Allowed list operator:

one_of

Example XML:

<Limit>
    <Operator>one_of</Operator>
    <AllowedValues>
        <TextAllowedValue>EP</TextAllowedValue>
        <TextAllowedValue>UP</TextAllowedValue>
        <TextAllowedValue>VE</TextAllowedValue>
    </AllowedValues>
</Limit>

Example JSON:

"limit": {
    "operator": "one_of",
    "allowedValues": ["EP", "UP", "VE"]
}

In XML, allowed values are represented by typed elements:

• NumericAllowedValue
• TextAllowedValue

In JSON, allowed values are represented as native JSON numbers or strings.

2.11 Final result

The final result is a simple procedure-level summary. It intentionally does not reference specimens, tests, or parameters. This supports easy adoption and allows exchange of final results without specimen details.

2.11.1 Fields

Field	Required	Type	Description
OverallEvaluation / overallEvaluation	Yes	Evaluation enum	Overall procedure result.
TestSummaries / testSummaries	No	Array	Per-test summary results.

2.11.2 Test summary

Field	Required	Type	Description
name	Yes	Text	Test name.
Evaluation / evaluation	Yes	Evaluation enum	Summary evaluation for that test name.
Documents / documents	No	Array	Linked documents.

2.12 Document

A document represents a linked reference to an external file, such as a test curve, raw data table, or photographic evidence.

2.12.1 Fields

Field	Required	Type	Description
PathOrUrl / pathOrUrl	Yes	Text	Source file path or web URL resolving to the document.
Name / name	No	Text	Human-readable document name or description.

Relative URLs are resolved relative to the exchange document location. Importers must not automatically fetch remote URLs unless explicitly configured. Paths containing parent directory traversal should be rejected.

2.13 Standard CIPP test matrix

2.13.1 Tests and parameters

Test name	Parameter name	Value type	Unit	Notes
FlexuralModulus	FlexuralModulus	Number	MPa	Final flexural modulus.
FlexuralStrength	FlexuralStrength	Number	MPa	Final flexural strength.
WallThickness	CompositeThickness	Number	mm	Composite wall thickness.
WallThickness	TotalThickness	Number	mm	Total wall thickness.
CreepTendency	CreepTendency	Number	%	Final creep tendency.
CircumferentialModulus	CircumferentialModulus	Number	MPa	Final circumferential modulus.
InitialRingStiffness	InitialRingStiffness	Number	Pa	Final initial ring stiffness.
Density	Density	Number	g/cm3	Final density.
WaterTightness	WaterTightnessResult	Text	none	Allowed values: tight, leaking.
WaterTightness	LeakageRate	Number	L/m2	Optional quantitative leakage rate.
ResidualStyrene	SampleWeight	Number	mg	Informational sample weight.
ResidualStyrene	StyreneContentWeight	Number	mg/kg	Styrene content by weight.
ResidualStyrene	StyreneContentPercent	Number	%	Styrene content percentage.
Calcination	ResinContent	Number	%	Resin content.
Calcination	GlassContent	Number	%	Glass content.
Calcination	AggregateContent	Number	%	Aggregate content.
Calcination	TotalResidue	Number	%	Total residue.
SpectralAnalysis	IdentifiedResinType	Text	none	Allowed values: EP, UP, VE, PU, unknown, other.
DynamicMechanicalAnalysis	StorageModulus	Number	MPa	Storage modulus.
ThermalAnalysis	TG1	Number	Cel	Glass transition temperature 1.
ThermalAnalysis	TG2	Number	Cel	Glass transition temperature 2.
ThermalAnalysis	DeltaTG	Number	K	Difference between glass transition temperatures.
ThermalAnalysis	EnthalpyValue	Number	J/g	Numeric enthalpy value.
ThermalAnalysis	ReactionType	Text	none	Allowed values: exotherm, endotherm.
LongTermReduction	LongTermReductionPercent	Number	%	Long-term reduction as percentage.

2.13.2 Standard conditions

Test name	Condition name	Value type	Unit	Notes
WaterTightness	TestDuration	Number	min	Test duration.
WaterTightness	TestPressure	Number	bar	Test pressure.

3. Format rules

3.1 Date and time rules

IsyLab uses a strict ISO 8601 profile.

3.1.1 Date values

Date values must use this format:

YYYY-MM-DD

Example:

2024-05-14

Applicable fields:

• ExtractionDate
• TestDate
• extractionDate
• testDate

3.1.2 Time values

Time values must use UTC with seconds. Fractional seconds are allowed but optional.

hh:mm:ssZ
hh:mm:ss.sssZ

Example:

13:30:00Z
13:30:00.123Z

Applicable fields:

• ExtractionTime
• TestTime
• extractionTime
• testTime

Invalid examples:

13:30Z
13:30
13:30:00

3.1.3 Date-time values

Date-time values must use UTC with seconds. Fractional seconds are allowed but optional.

YYYY-MM-DDThh:mm:ssZ
YYYY-MM-DDThh:mm:ss.sssZ

Example:

2024-10-26T14:32:00Z
2024-10-26T14:32:00.123Z

Applicable fields:

• GenerationTime
• generationTime

Invalid examples:

2024-10-26T14:32Z
2024-10-26 14:32:00Z
2024-10-26T14:32:00+01:00

All date-time and time values must be converted to UTC before export.

3.2 Decimal and numeric rules

3.2.1 XML

XML numeric parameter values must use the NumericValue element.

XML numeric limit values, condition values, extraction distance values, and numeric parameter values store numbers as element text.

Numeric XML values must use this lexical representation:

-?[0-9]+(\.[0-9]+)?

Examples:

12500
12500.0
-2.5
0.65

The decimal separator must be a period.

Invalid examples:

12,5
1 250.0
1.250,0

Correct numeric parameter example:

<Parameter id="PARAM-001" name="FlexuralModulus">
    <NumericValue>12500.0</NumericValue>
    <Unit>MPa</Unit>
    <Evaluation>pass</Evaluation>
</Parameter>

3.2.2 JSON

JSON numeric values must be represented as native JSON numbers, not strings.

Correct:

{
    "value": 12500.0
}

Incorrect:

{
    "value": "12500.0"
}

Text values must be represented as JSON strings.

Correct:

{
    "value": "tight"
}

3.3 Units

IsyLab uses UCUM unit codes.

All quantitative values that have a unit must use a valid UCUM unit code. The schema validates only the lexical shape of unit codes. Full UCUM validation requires a UCUM-aware validator.

Qualitative values must not carry a unit.

3.3.1 Common UCUM units used by IsyLab

Meaning	UCUM code
Megapascal	MPa
Millimeter	mm
Percent	%
Minute	min
Bar	bar
Gram per cubic centimeter	g/cm3
Milligram	mg
Milligram per kilogram	mg/kg
Celsius temperature	Cel
Kelvin temperature difference	K
Joule per gram	J/g
Liter per square meter	L/m2
Pascal	Pa

3.3.2 Qualitative values

Qualitative values do not use units.

In XML, textual qualitative values must use TextValue.

Correct XML:

<Parameter id="PARAM-001" name="WaterTightnessResult">
    <TextValue>tight</TextValue>
    <Evaluation>pass</Evaluation>
</Parameter>

Incorrect XML:

<Parameter id="PARAM-001" name="WaterTightnessResult">
    <TextValue>tight</TextValue>
    <Unit>1</Unit>
    <Evaluation>pass</Evaluation>
</Parameter>

In JSON, textual qualitative values are represented as strings.

Correct JSON:

{
    "id": "PARAM-001",
    "name": "WaterTightnessResult",
    "value": "tight",
    "evaluation": "pass"
}

Incorrect JSON:

{
    "id": "PARAM-001",
    "name": "WaterTightnessResult",
    "value": "tight",
    "unit": "1",
    "evaluation": "pass"
}

3.3.3 Dimensionless numeric values

If an exported parameter is a strictly dimensionless number, such as a ratio, a factor, or a simple count, it still counts as a quantitative value. Because IsyLab requires a metric unit for all quantitative limits and values, the official UCUM code for dimensionless quantities must be used. This code is the string "1".

Correct JSON:

{
    "id": "PARAM-026",
    "name": "ReductionFactor",
    "value": 0.85,
    "unit": "1",
    "evaluation": "pass"
}

Correct XML:

<Parameter id="PARAM-026" name="ReductionFactor">
    <NumericValue>0.85</NumericValue>
    <Unit>1</Unit>
    <Evaluation>pass</Evaluation>
</Parameter>

3.4 Extraction distance

ExtractionDistance represents the longitudinal positional coordinate of the extracted sample. The value 0.0 represents the inflow node. The distance must be combined with a valid metric length unit (e.g., m or cm).

Example XML:

<ExtractionDistance>
    <NumericValue>12.5</NumericValue>
    <Unit>m</Unit>
</ExtractionDistance>

Example JSON:

"extractionDistance": {
    "value": 12.5,
    "unit": "m"
}

3.5 Extraction clock position

ExtractionClockPosition represents the radial extraction position on the pipe circumference. It is not a time value.

The format uses the standard 12-hour clock reference system for circumferential extraction positions as defined in the DIN EN 13508-2 standard, where 12:00 corresponds to the pipe crown.

Allowed format:

HH:mm

Allowed range:

01:00 through 12:59

Examples:

12:00
03:00
06:00
09:00
12:30

The value 12:00 represents the top crown position.

The value 06:00 represents the invert position.

3.6 Identifier rules

The schema enforces strict formatting for referencing identifiers.

3.6.1 General Identifiers (id, name)

General identifiers must be between 1 and 128 characters long. They must start with an alphanumeric character. They may contain dashes, underscores, periods, colons, and spaces, but spaces are explicitly forbidden as the first or last character.

Allowed pattern:

[A-Za-z0-9]([A-Za-z0-9_.:\- ]*[A-Za-z0-9_.:\-])?

Examples:

SPEC-01
Flexural Modulus 1
PARAM-001

3.6.2 Mate Installation Identifier (mateId)

The mateId is strictly constrained to exactly 7 alphanumeric characters. No spaces or special characters are allowed at all.

Allowed pattern:

[A-Za-z0-9]{7}

Examples:

00001X1
A1B2C3D

4. Implementation

4.1 Conformance levels

4.1.1 Level 1: Generic structural parser

A Level 1 implementation can:

• Parse the document structure.
• Read header data.
• Read procedures.
• Read final results.
• Read specimens, tests, conditions, and parameters if present.
• Validate required structural fields.
• Drop unknown Test or Parameter entries based on unsupported names.

A Level 1 implementation does not need to understand all CIPP-specific test semantics.

4.1.2 Level 2: Core CIPP parser

A Level 2 implementation can:

• Do everything required for Level 1.
• Understand all standard test names listed in this document.
• Understand all standard parameter names listed in this document.
• Interpret UCUM unit codes used by the standard test matrix.
• Import known conditions and known parameters into structured CIPP-specific fields.

4.1.3 Level 3: Validating parser

A Level 3 implementation can:

• Do everything required for Level 2.
• Validate values against expected value types.
• Validate UCUM unit compatibility for known parameters.
• Validate limits against operators.
• Optionally recalculate parameter evaluations where enough information is available.
• Detect inconsistencies between values, limits, units, and evaluations.

4.2 Unknown test and parameter behavior

Unknown Test or Parameter entries must be dropped by importing systems.

This rule applies to unknown values of:

• XML <Test name="...">
• XML <Parameter name="...">
• JSON test.name
• JSON parameter.name

Unknown structural elements or unknown JSON object properties are not part of IsyLab and may fail schema validation.

Recommended importer behavior:

1. Validate the document structure.
2. Read known tests and parameters.
3. Drop unknown tests and unknown parameters.
4. Continue importing the remaining known data.
5. Optionally log dropped entries for diagnostics.

4.3 Handling of empty arrays in JSON

The IsyLab JSON schema requires all arrays to contain at least one item ("minItems": 1). Empty JSON arrays (e.g., "conditions": []) are strictly invalid and will cause a schema validation failure.

When exporting optional collections that contain no data, the property must be omitted entirely from the JSON object instead of passing an empty array.

Exporting systems should ensure that JSON serializers are configured to ignore empty collections automatically (e.g., by utilizing settings like NullValueHandling.Ignore or by configuring stringifiers to skip empty enumerables).

5. Versioning

The root object or root element carries the format version.

XML:

<IsyLab version="1.0">

JSON:

{
    "type": "IsyLab",
    "version": "1.0"
}

Versioning rules:

• 1.0 is the initial stable release.
• 1.1, 1.2, and other 1.x versions are backwards compatible with 1.0.
• 2.0 means a breaking change that is not backwards compatible with 1.0.
• Importers that support 1.0 may reject 2.0 documents.
• Importers that support 1.0 should accept compatible 1.x documents if unsupported additions can be ignored safely.