This is MRDI.info, produced by Macaulay2, version 1.26.05

MRDI -- serialization using the mrdi file format
************************************************

Description
===========

The MRDI package provides tools for serializing and deserializing mathematical
objects in Macaulay2 using the MRDI file format, a JSON-based format for
storing and sharing results in computer algebra without losing accuracy.  The
format was developed as part of the Mathematics Research Data Initiative
(MaRDI) (see https://www.mardi4nfdi.de/ ) and is described in the paper:

Antony Della Vecchia, Michael Joswig, and Benjamin Lorenz, A FAIR file format
for mathematical software (see https://doi.org/10.1007/978-3-031-64529-7_25 ),
Mathematical software—ICMS 2024, 234–244, Lecture Notes in Comput. Sci., 14749,
Springer, Cham.

Each serialized object carries a namespace (_ns) identifying the originating
software system and version, a type descriptor (_type) that may include
recursive parameters, the actual data, and optionally a set of references
(_refs) keyed by UUIDs.

The package can serialize and deserialize integers, rings (see ZZ (Macaulay2Doc),
see QQ (Macaulay2Doc), finite prime fields, Galois
fields), polynomial rings, ring elements, ideals, and matrices.  It can also
load and save objects using the OSCAR namespace, enabling interoperability with
the OSCAR (see https://www.oscar-system.org/ ) computer algebra system.

The namespace mechanism also makes it possible to define custom serialization
formats for exchanging data with other software systems.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w]                                                         |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = monomialCurveIdeal(R, {1,2,3})                                      |
|                                                                             |
|             2                    2                                          |
|o2 = ideal (z  - y*w, y*z - x*w, y  - x*z)                                   |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : s = saveMRDI I                                                          |
|                                                                             |
|o3 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":    |
|     "Ideal"}, "data": [[[["0", "0", "2", "0"], ["1", "1"]], [["0", "1", "0",|
|     "1"], ["-1", "1"]]], [[["0", "1", "1", "0"], ["1", "1"]], [["1", "0",   |
|     "0", "1"], ["-1", "1"]]], [[["0", "2", "0", "0"], ["1", "1"]], [["1",   |
|     "0", "1", "0"], ["-1", "1"]]]], "_ns": {"Macaulay2":                    |
|     ["https://macaulay2.com", "1.26.05"]}, "_refs":                         |
|     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type": |
|     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables": |
|     ["x", "y", "z", "w"]}}}}                                                |
+-----------------------------------------------------------------------------+
|i4 : loadMRDI s                                                              |
|                                                                             |
|             2                    2                                          |
|o4 = ideal (z  - y*w, y*z - x*w, y  - x*z)                                   |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

Author
======

  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 0.1 of MRDI, released April 25, 2026.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{MRDISource,                                                            |
|  title = {{MRDI: serializing algebraic data with .mrdi files. Version~0.1}},|
|  author = {Doug Torrance},                                                  |
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
+-----------------------------------------------------------------------------+

Exports
=======

  * Functions and commands
      * addLoadMethod -- register a method for
        deserializing a type from MRDI format
      * addNamespace -- register a namespace for MRDI
        serialization
      * addSaveMethod -- register a method for
        serializing a type to MRDI format
      * loadMRDI -- deserialize a Macaulay2 object from MRDI
        format
      * saveMRDI -- serialize a Macaulay2 object to MRDI JSON
        format
      * validateMRDI -- validate an MRDI JSON object
        against the format specification
  * Methods
      * "addLoadMethod(List,Function)" -- see addLoadMethod,
        -- register a method for deserializing a type from MRDI
        format
      * "addLoadMethod(String,Function)" -- see addLoadMethod,
        -- register a method for deserializing a type from MRDI
        format
      * "addNamespace(String,String,String)" -- see addNamespace,
        -- register a namespace for MRDI serialization
      * "addSaveMethod(Type)" -- see addSaveMethod, --
        register a method for serializing a type to MRDI format
      * "addSaveMethod(Type,Function)" -- see addSaveMethod,
        -- register a method for serializing a type to MRDI
        format
      * "addSaveMethod(Type,Function,Function)" -- see addSaveMethod,
        -- register a method for serializing a type to MRDI
        format
      * "loadMRDI(HashTable)" -- see loadMRDI, -- deserialize a
        Macaulay2 object from MRDI format
      * "loadMRDI(String)" -- see loadMRDI, -- deserialize a
        Macaulay2 object from MRDI format
      * "saveMRDI(Thing)" -- see saveMRDI, -- serialize a
        Macaulay2 object to MRDI JSON format
      * "validateMRDI(HashTable)" -- see validateMRDI, --
        validate an MRDI JSON object against the format specification
      * "validateMRDI(String)" -- see validateMRDI, --
        validate an MRDI JSON object against the format specification
      * "validateMRDI(Thing)" -- see validateMRDI, --
        validate an MRDI JSON object against the format specification
  * Symbols
      * "UseID" -- see addSaveMethod, -- register a method
        for serializing a type to MRDI format
      * Namespace -- option specifying the namespace for MRDI
        serialization
      * "ToString" -- see saveMRDI, -- serialize a Macaulay2
        object to MRDI JSON format

For the programmer
==================

The object MRDI, is a package (Macaulay2Doc), defined
in MRDI.m2.

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:487:0.

saveMRDI -- serialize a Macaulay2 object to MRDI JSON format
************************************************************

  * Usage:
        saveMRDI x
  * Inputs:
      * x, a thing (Macaulay2Doc), a Macaulay2 object to serialize
        (must have a save method registered via addSaveMethod)
  * Optional inputs (Macaulay2Doc),:
      * FileName => a string (Macaulay2Doc), default value null,
        if given, the JSON output is written to this file
      * Namespace => a string (Macaulay2Doc), default value
        "Macaulay2", the namespace to use for serialization
      * ToString => a Boolean value (Macaulay2Doc), default
        value true, if true (Macaulay2Doc), then the output is a
        JSON string; if false (Macaulay2Doc), then the output is a
        hash table (Macaulay2Doc), representing the JSON
        structure
  * Outputs:
      * a string (Macaulay2Doc), or a hash table (Macaulay2Doc),

Description
===========

This function serializes a Macaulay2 object into a JSON string following the
MRDI file format specification.  The output includes a namespace (_ns)
identifying the software system and its version, a type descriptor (_type), and
the data.

For parametric types such as PolynomialRing (Macaulay2Doc),
see RingElement (Macaulay2Doc),
Ideal (Macaulay2Doc), and Matrix (Macaulay2Doc), the
type descriptor includes a params field referencing the parent ring.  Rings and
other objects marked with UseID, are assigned UUIDs so
that multiple objects sharing the same ring refer to it by UUID rather than
repeating its full description.

We may serialize a simple integer.

+--------------------------------------------------------------------------+
|i1 : saveMRDI 5                                                           |
|                                                                          |
|o1 = {"_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]}, "_type":|
|     "ZZ", "data": "5"}                                                   |
+--------------------------------------------------------------------------+

We can also serialize a polynomial ring element.

+-----------------------------------------------------------------------------+
|i2 : R = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i3 : f = x^2 + y*z - 3*x                                                     |
|                                                                             |
|      2                                                                      |
|o3 = x  + y*z - 3x                                                           |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : saveMRDI f                                                              |
|                                                                             |
|o4 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":    |
|     "RingElement"}, "data": [[["2", "0", "0"], ["1", "1"]], [["0", "1",     |
|     "1"], ["1", "1"]], [["1", "0", "0"], ["-3", "1"]]], "_ns": {"Macaulay2":|
|     ["https://macaulay2.com", "1.26.05"]}, "_refs":                         |
|     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type": |
|     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables": |
|     ["x", "y", "z"]}}}}                                                     |
+-----------------------------------------------------------------------------+

Ideals are serialized similarly.

+----------------------------------------------------------------------------+
|i5 : I = ideal(x^2 - y, y^2 - z)                                            |
|                                                                            |
|             2       2                                                      |
|o5 = ideal (x  - y, y  - z)                                                 |
|                                                                            |
|o5 : Ideal of R                                                             |
+----------------------------------------------------------------------------+
|i6 : saveMRDI I                                                             |
|                                                                            |
|o6 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":   |
|     "Ideal"}, "data": [[[["2", "0", "0"], ["1", "1"]], [["0", "1", "0"],   |
|     ["-1", "1"]]], [[["0", "2", "0"], ["1", "1"]], [["0", "0", "1"], ["-1",|
|     "1"]]]], "_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]},   |
|     "_refs": {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": |
|     {"_type": "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data":    |
|     {"variables": ["x", "y", "z"]}}}}                                      |
+----------------------------------------------------------------------------+

The output can be written directly to a file using the FileName (Macaulay2Doc),
option.

+-----------------------------------------------------------------------------+
|i7 : fn = temporaryFileName() | ".mrdi"                                      |
|                                                                             |
|o7 = /tmp/M2-36605-0/0.mrdi                                                  |
+-----------------------------------------------------------------------------+
|i8 : saveMRDI(f, FileName => fn)                                             |
|                                                                             |
|o8 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":    |
|     "RingElement"}, "data": [[["2", "0", "0"], ["1", "1"]], [["0", "1",     |
|     "1"], ["1", "1"]], [["1", "0", "0"], ["-3", "1"]]], "_ns": {"Macaulay2":|
|     ["https://macaulay2.com", "1.26.05"]}, "_refs":                         |
|     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type": |
|     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables": |
|     ["x", "y", "z"]}}}}                                                     |
+-----------------------------------------------------------------------------+
|i9 : removeFile fn                                                           |
+-----------------------------------------------------------------------------+

The Namespace, option selects a different namespace for
serialization, such as OSCAR.

+--------------------------------------------------------------------+
|i10 : saveMRDI(5, Namespace => "Oscar")                             |
|                                                                    |
|o10 = {"_ns": {"Oscar": ["https://github.com/oscar-system/Oscar.jl",|
|      "1.6.0"]}, "_type": {"params": {"_type": "ZZRing"}, "name":   |
|      "ZZRingElem"}, "data": "5"}                                   |
+--------------------------------------------------------------------+

Setting ToString => false returns the hash table representation instead of a
JSON string.  This

+-----------------------------------------------------------------------------+
|i11 : saveMRDI(5, ToString => false)                                         |
|                                                                             |
|o11 = HashTable{"_ns" => HashTable{"Macaulay2" => {https://macaulay2.com,    |
|                "_type" => ZZ                                                |
|                "data" => 5                                                  |
|                                                                             |
|o11 : HashTable                                                              |
|-----------------------------------------------------------------------------|
|1.26.05}}}                                                                   |
+-----------------------------------------------------------------------------+

To see which types have built-in save methods for a given namespace, call
methods (Macaulay2Doc), as follows.

+----------------------------------------------------+
|i12 : methods {"Macaulay2", saveMRDI}               |
|                                                    |
|o12 = {0 => ({Macaulay2, saveMRDI}, ZZ)            }|
|      {1 => ({Macaulay2, saveMRDI}, Matrix)        }|
|      {2 => ({Macaulay2, saveMRDI}, GaloisField)   }|
|      {3 => ({Macaulay2, saveMRDI}, Ideal)         }|
|      {4 => ({Macaulay2, saveMRDI}, RingElement)   }|
|      {5 => ({Macaulay2, saveMRDI}, PolynomialRing)}|
|      {6 => ({Macaulay2, saveMRDI}, Ring)          }|
|      {7 => ({Macaulay2, saveMRDI}, QuotientRing)  }|
|                                                    |
|o12 : NumberedVerticalList                          |
+----------------------------------------------------+
|i13 : methods {"Oscar", saveMRDI}                   |
|                                                    |
|o13 = {0 => ({Oscar, saveMRDI}, RingElement)   }    |
|      {1 => ({Oscar, saveMRDI}, Ring)          }    |
|      {2 => ({Oscar, saveMRDI}, PolynomialRing)}    |
|      {3 => ({Oscar, saveMRDI}, QQ)            }    |
|      {4 => ({Oscar, saveMRDI}, ZZ)            }    |
|                                                    |
|o13 : NumberedVerticalList                          |
+----------------------------------------------------+

Additional types can be supported by calling addSaveMethod.

Caveat
======

Not all Macaulay2 types have save methods defined.  Attempting to serialize an
unsupported type will produce an error. Quotient rings other than finite prime
fields are not yet supported.

See also
========

  * loadMRDI -- deserialize a Macaulay2 object from MRDI
    format

Ways to use saveMRDI:
=====================

  * "saveMRDI(Thing)"

For the programmer
==================

The object saveMRDI, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:577:0.

addSaveMethod -- register a method for serializing a type to MRDI format
************************************************************************

  * Usage:
        addSaveMethod T
        addSaveMethod(T, dataFunc)
        addSaveMethod(T, paramsFunc, dataFunc)
  * Inputs:
      * T, a type (Macaulay2Doc), the Macaulay2 type to be
        serialized
      * dataFunc, a function (Macaulay2Doc), a function that
        takes an object of type T and returns the data to be stored in the data
        field of the MRDI JSON
      * paramsFunc, a function (Macaulay2Doc), a function that
        takes an object of type T and returns the parameter object (e.g., the
        coefficient ring of a polynomial ring), which will itself be serialized
        recursively
  * Optional inputs (Macaulay2Doc),:
      * UseID => a Boolean value (Macaulay2Doc), default value
        false, if true, objects of this type are assigned UUIDs so they can be
        referenced rather than duplicated
      * Name => a function (Macaulay2Doc), default value
        FunctionClosure[../../m2/classes.m2:113:45-113:55], a function (or
        string) that determines the type name string for the _type field.  By
        default, the class (Macaulay2Doc), of each object (as a
        string) is used.
      * Namespace => a string (Macaulay2Doc), default value
        "Macaulay2", the namespace to register this save method under

Description
===========

This function registers a serialization method for the given type so that
saveMRDI, knows how to convert objects of that type into MRDI JSON
format.

The zero-argument form addSaveMethod T is for types with no data and no
parameters (the MRDI output will contain only a _type field).

The one-argument form addSaveMethod(T, dataFunc) is for basic (non-parametric)
types whose MRDI representation needs only a _type name and data.  The dataFunc
receives the object and should return the data portion.

The two-argument form addSaveMethod(T, paramsFunc, dataFunc) is for parametric
types.  The paramsFunc returns an object representing the type's parameter
(which will be recursively serialized into the _type.params field), and
dataFunc returns the data.

The UseID, option causes objects of this type to be
assigned RFC 9562 version 4 UUIDs upon serialization. This is important for
types like polynomial rings that may be shared by many objects: the ring is
stored once in the _refs section and referenced by UUID elsewhere.

The Namespace, option allows registering save methods for
different namespaces.  This is how OSCAR serialization support is implemented
alongside Macaulay2's own namespace.

Here we register a save method for a custom namespace.

+----------------------------------------------------------------------------+
|i1 : addNamespace("MySystem", "https://example.com", "1.0")                 |
+----------------------------------------------------------------------------+
|i2 : addSaveMethod(ZZ, identity, Name => "MyInt", Namespace => "MySystem")  |
+----------------------------------------------------------------------------+
|i3 : saveMRDI(42, Namespace => "MySystem")                                  |
|                                                                            |
|o3 = {"_ns": {"MySystem": ["https://example.com", "1.0"]}, "_type": "MyInt",|
|     "data": "42"}                                                          |
+----------------------------------------------------------------------------+

See also
========

  * saveMRDI -- serialize a Macaulay2 object to MRDI JSON
    format

Ways to use addSaveMethod:
==========================

  * "addSaveMethod(Type)"
  * "addSaveMethod(Type,Function)"
  * "addSaveMethod(Type,Function,Function)"

For the programmer
==================

The object addSaveMethod, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:736:0.

loadMRDI -- deserialize a Macaulay2 object from MRDI format
***********************************************************

  * Usage:
        loadMRDI s
  * Inputs:
      * s, a string (Macaulay2Doc), or a hash table (Macaulay2Doc),
        a JSON string in the MRDI file format or
        parsed JSON hash table (e.g., from fromJSON (JSON))
  * Outputs:
      * a thing (Macaulay2Doc), the deserialized Macaulay2 object;

Description
===========

This method parses an MRDI-formatted JSON string (or hash table) and
reconstructs the corresponding Macaulay2 object.  The namespace field (_ns) in
the JSON determines which set of load methods is used for deserialization.

This function handles the _refs section of the JSON to reconstruct shared
references via UUIDs.  For example, when an ideal and a ring element both refer
to the same polynomial ring, the ring is constructed once and shared.

A polynomial ring element can be round-tripped through the format.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z,w];                                                        |
+-----------------------------------------------------------------------------+
|i2 : f = x^2 + y*z                                                           |
|                                                                             |
|      2                                                                      |
|o2 = x  + y*z                                                                |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : s = saveMRDI f                                                          |
|                                                                             |
|o3 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":    |
|     "RingElement"}, "data": [[["2", "0", "0", "0"], ["1", "1"]], [["0", "1",|
|     "1", "0"], ["1", "1"]]], "_ns": {"Macaulay2": ["https://macaulay2.com", |
|     "1.26.05"]}, "_refs": {"6caf806b-9118-4741-bec7-217a71096848": {"_type":|
|     {"params": {"_type": "Ring", "data": "QQ"}, "name": "PolynomialRing"},  |
|     "data": {"variables": ["x", "y", "z", "w"]}}}}                          |
+-----------------------------------------------------------------------------+
|i4 : g = loadMRDI s                                                          |
|                                                                             |
|      2                                                                      |
|o4 = x  + y*z                                                                |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : f === g                                                                 |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

The same works for ideals.

+-----------------------------------------------------------------------------+
|i6 : I = monomialCurveIdeal(R, {1,2,3})                                      |
|                                                                             |
|             2                    2                                          |
|o6 = ideal (z  - y*w, y*z - x*w, y  - x*z)                                   |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : s = saveMRDI I                                                          |
|                                                                             |
|o7 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":    |
|     "Ideal"}, "data": [[[["0", "0", "2", "0"], ["1", "1"]], [["0", "1", "0",|
|     "1"], ["-1", "1"]]], [[["0", "1", "1", "0"], ["1", "1"]], [["1", "0",   |
|     "0", "1"], ["-1", "1"]]], [[["0", "2", "0", "0"], ["1", "1"]], [["1",   |
|     "0", "1", "0"], ["-1", "1"]]]], "_ns": {"Macaulay2":                    |
|     ["https://macaulay2.com", "1.26.05"]}, "_refs":                         |
|     {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type": |
|     "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables": |
|     ["x", "y", "z", "w"]}}}}                                                |
+-----------------------------------------------------------------------------+
|i8 : J = loadMRDI s                                                          |
|                                                                             |
|             2                    2                                          |
|o8 = ideal (z  - y*w, y*z - x*w, y  - x*z)                                   |
|                                                                             |
|o8 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i9 : I === J                                                                 |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

Objects can be loaded from a file as well using get (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i10 : fn = temporaryFileName() | ".mrdi"                                     |
|                                                                             |
|o10 = /tmp/M2-36561-0/0.mrdi                                                 |
+-----------------------------------------------------------------------------+
|i11 : saveMRDI(I, FileName => fn)                                            |
|                                                                             |
|o11 = {"_type": {"params": "6caf806b-9118-4741-bec7-217a71096848", "name":   |
|      "Ideal"}, "data": [[[["0", "0", "2", "0"], ["1", "1"]], [["0", "1",    |
|      "0", "1"], ["-1", "1"]]], [[["0", "1", "1", "0"], ["1", "1"]], [["1",  |
|      "0", "0", "1"], ["-1", "1"]]], [[["0", "2", "0", "0"], ["1", "1"]],    |
|      [["1", "0", "1", "0"], ["-1", "1"]]]], "_ns": {"Macaulay2":            |
|      ["https://macaulay2.com", "1.26.05"]}, "_refs":                        |
|      {"6caf806b-9118-4741-bec7-217a71096848": {"_type": {"params": {"_type":|
|      "Ring", "data": "QQ"}, "name": "PolynomialRing"}, "data": {"variables":|
|      ["x", "y", "z", "w"]}}}}                                               |
+-----------------------------------------------------------------------------+
|i12 : J = loadMRDI get fn                                                    |
|                                                                             |
|              2                    2                                         |
|o12 = ideal (z  - y*w, y*z - x*w, y  - x*z)                                  |
|                                                                             |
|o12 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i13 : I === J                                                                |
|                                                                             |
|o13 = true                                                                   |
+-----------------------------------------------------------------------------+
|i14 : removeFile fn                                                          |
+-----------------------------------------------------------------------------+

A parsed hash table can also be passed directly, for instance when using
ToString => false with saveMRDI.

+-----------------------------------------------------------------------------+
|i15 : h = saveMRDI(42, ToString => false)                                    |
|                                                                             |
|o15 = HashTable{"_ns" => HashTable{"Macaulay2" => {https://macaulay2.com,    |
|                "_type" => ZZ                                                |
|                "data" => 42                                                 |
|                                                                             |
|o15 : HashTable                                                              |
|-----------------------------------------------------------------------------|
|1.26.05}}}                                                                   |
+-----------------------------------------------------------------------------+
|i16 : loadMRDI h                                                             |
|                                                                             |
|o16 = 42                                                                     |
+-----------------------------------------------------------------------------+

The MRDI format supports cross-system interoperability. Objects serialized by
the OSCAR computer algebra system can also be loaded.

+-----------------------------------------------------------------------------+
|i17 : loadMRDI "{\"_ns\":{\"Oscar\":[\"https://github.com/oscar-system/Oscar.|
|                                                                             |
|o17 = 42                                                                     |
|-----------------------------------------------------------------------------|
|jl\",\"1.5.0\"]},\"_type\":\"ZZRingElem\",\"data\":\"42\"}"                  |
+-----------------------------------------------------------------------------+

To see which types have built-in load methods for a given namespace, call
methods (Macaulay2Doc), as follows.

+----------------------------------------------------+
|i18 : methods {"Macaulay2", loadMRDI}               |
|                                                    |
|o18 = {0 => ({Macaulay2, loadMRDI}, Ring)          }|
|      {1 => ({Macaulay2, loadMRDI}, ZZ)            }|
|      {2 => ({Macaulay2, loadMRDI}, Matrix)        }|
|      {3 => ({Macaulay2, loadMRDI}, GaloisField)   }|
|      {4 => ({Macaulay2, loadMRDI}, PolynomialRing)}|
|      {5 => ({Macaulay2, loadMRDI}, Ideal)         }|
|      {6 => ({Macaulay2, loadMRDI}, QuotientRing)  }|
|      {7 => ({Macaulay2, loadMRDI}, RingElement)   }|
|                                                    |
|o18 : NumberedVerticalList                          |
+----------------------------------------------------+
|i19 : methods {"Oscar", loadMRDI}                   |
|                                                    |
|o19 = {0 => ({Oscar, loadMRDI}, ZZRing)       }     |
|      {1 => ({Oscar, loadMRDI}, String)       }     |
|      {2 => ({Oscar, loadMRDI}, Base.Int)     }     |
|      {3 => ({Oscar, loadMRDI}, MPolyRingElem)}     |
|      {4 => ({Oscar, loadMRDI}, MPolyRing)    }     |
|      {5 => ({Oscar, loadMRDI}, QQFieldElem)  }     |
|      {6 => ({Oscar, loadMRDI}, QQField)      }     |
|      {7 => ({Oscar, loadMRDI}, Float64)      }     |
|      {8 => ({Oscar, loadMRDI}, PolyRingElem) }     |
|      {9 => ({Oscar, loadMRDI}, FiniteField)  }     |
|      {10 => ({Oscar, loadMRDI}, PolyRing)    }     |
|      {11 => ({Oscar, loadMRDI}, ZZRingElem)  }     |
|                                                    |
|o19 : NumberedVerticalList                          |
+----------------------------------------------------+

Additional types can be supported by calling addLoadMethod.

Caveat
======

If the JSON string references a namespace or type for which no load method has
been registered, an error is produced. Use addLoadMethod,
to register handlers for custom types and addNamespace, to
register new namespaces.

See also
========

  * saveMRDI -- serialize a Macaulay2 object to MRDI JSON
    format

Ways to use loadMRDI:
=====================

  * "loadMRDI(HashTable)"
  * "loadMRDI(String)"

For the programmer
==================

The object loadMRDI, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:657:0.

addLoadMethod -- register a method for deserializing a type from MRDI format
****************************************************************************

  * Usage:
        addLoadMethod(typeName, f)
  * Inputs:
      * typeName, a string (Macaulay2Doc), or a list (Macaulay2Doc),
        the type name as it appears in the _type field of
        the MRDI JSON, or a list of strings to add multiple load methods at the
        same time
      * f, a function (Macaulay2Doc), a function (params, data)
        -> Thing that reconstructs the object
  * Optional inputs (Macaulay2Doc),:
      * Namespace => a string (Macaulay2Doc), default value
        "Macaulay2", the namespace to register this method under

Description
===========

This methods registers a deserialization method so that loadMRDI,
knows how to reconstruct objects of a given type within a given
namespace.

The namespace allows the same file format to be used across different computer
algebra systems.  The Macaulay2 namespace is "Macaulay2" and the OSCAR
namespace is "Oscar".  Each namespace maintains its own type registry.  Use
addNamespace, to register a new namespace before adding
load methods to it.

The loading function f receives two arguments:

  * params: For parametric types (e.g., see RingElement (Macaulay2Doc)),
    this is the already-deserialized parameter
    (e.g., the parent ring).  For non-parametric types (e.g., see ZZ (Macaulay2Doc)),
    this is null (Macaulay2Doc).
  * data:  The contents of the data field from the JSON, recursively
    deserialized.

The List (Macaulay2Doc), form allows registering the same function
for multiple type names at once, which is useful when systems use different
names for equivalent types.

Here we register a load method for a custom namespace.

+-----------------------------------------------------------------------------+
|i1 : addNamespace("MySystem", "https://example.com", "1.0")                  |
+-----------------------------------------------------------------------------+
|i2 : addLoadMethod("MyInt",                                                  |
|         (params, data) -> value data,                                       |
|         Namespace => "MySystem")                                            |
|                                                                             |
|o2 = FunctionClosure[currentString:3:4-3:32]                                 |
|                                                                             |
|o2 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i3 : loadMRDI "{\"_ns\":{\"MySystem\":[\"https://example.com\",\"1.0\"]},\"_ |
|                                                                             |
|o3 = 42                                                                      |
|-----------------------------------------------------------------------------|
|type\":\"MyInt\",\"data\":\"42\"}"                                           |
+-----------------------------------------------------------------------------+

See also
========

  * loadMRDI -- deserialize a Macaulay2 object from MRDI
    format

Ways to use addLoadMethod:
==========================

  * "addLoadMethod(List,Function)"
  * "addLoadMethod(String,Function)"

For the programmer
==================

The object addLoadMethod, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:795:0.

Namespace -- option specifying the namespace for MRDI serialization
*******************************************************************

Description
===========

A symbol used as an option to addSaveMethod,
addLoadMethod, and saveMRDI, to specify which
namespace to use.

Different namespaces allow the same MRDI file format to represent objects from
different computer algebra systems. The "Macaulay2" and "Oscar" namespaces are
built in.  Custom namespaces can be registered with addNamespace.

When passed to saveMRDI, this determines which set of save
methods is used and what appears in the _ns field of the JSON output.

When passed to addSaveMethod, or addLoadMethod,
this determines which namespace the method is registered under.

The same object can be serialized under different namespaces.

+--------------------------------------------------------------------------+
|i1 : saveMRDI 5                                                           |
|                                                                          |
|o1 = {"_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]}, "_type":|
|     "ZZ", "data": "5"}                                                   |
+--------------------------------------------------------------------------+
|i2 : saveMRDI(5, Namespace => "Oscar")                                    |
|                                                                          |
|o2 = {"_ns": {"Oscar": ["https://github.com/oscar-system/Oscar.jl",       |
|     "1.6.0"]}, "_type": {"params": {"_type": "ZZRing"}, "name":          |
|     "ZZRingElem"}, "data": "5"}                                          |
+--------------------------------------------------------------------------+

Functions with optional argument named Namespace:
=================================================

  * "addLoadMethod(...,Namespace=>...)" -- see addLoadMethod,
    -- register a method for deserializing a type from MRDI
    format
  * "addSaveMethod(...,Namespace=>...)" -- see addSaveMethod,
    -- register a method for serializing a type to MRDI format
  * "saveMRDI(...,Namespace=>...)" -- see saveMRDI, --
    serialize a Macaulay2 object to MRDI JSON format

For the programmer
==================

The object Namespace, is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:892:0.

addNamespace -- register a namespace for MRDI serialization
***********************************************************

  * Usage:
        addNamespace(ns, url, ver)
  * Inputs:
      * ns, a string (Macaulay2Doc), the namespace identifier;
      * url, a string (Macaulay2Doc), the URL associated with the
        namespace;
      * ver, a string (Macaulay2Doc), the version string for the
        namespace;

Description
===========

This method registers a new namespace for use with saveMRDI,
and loadMRDI.  A namespace must be registered before any save
or load methods can be added to it using addSaveMethod, or
addLoadMethod.

The namespace, URL, and version are written into the _ns field of the MRDI JSON
output.

The "Macaulay2" and "Oscar" namespaces are registered automatically when the
package is loaded.

+-----------------------------------------------------------------------------+
|i1 : addNamespace("MySystem", "https://example.com", "1.0")                  |
+-----------------------------------------------------------------------------+
|i2 : addLoadMethod("MyInt",                                                  |
|         (params, data) -> value data,                                       |
|         Namespace => "MySystem")                                            |
|                                                                             |
|o2 = FunctionClosure[currentString:3:4-3:32]                                 |
|                                                                             |
|o2 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i3 : loadMRDI "{\"_ns\":{\"MySystem\":[\"https://example.com\",\"1.0\"]},\"_ |
|                                                                             |
|o3 = 42                                                                      |
|-----------------------------------------------------------------------------|
|type\":\"MyInt\",\"data\":\"42\"}"                                           |
+-----------------------------------------------------------------------------+

Ways to use addNamespace:
=========================

  * "addNamespace(String,String,String)"

For the programmer
==================

The object addNamespace, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:826:0.

validateMRDI -- validate an MRDI JSON object against the format specification
*****************************************************************************

  * Usage:
        validateMRDI s
  * Inputs:
      * s, a string (Macaulay2Doc), or a hash table (Macaulay2Doc),
        a JSON string or parsed JSON hash table to
        validate

Description
===========

Validates that a JSON string or hash table conforms to the MRDI file format
specification (see https://www.oscar-system.org/schemas/mrdi.json ). This
checks structural requirements such as:

  * the presence of a _type key
  * that _type is a string or an object with string-valued name
  * that _ns and _refs are objects (if present)
  * that all keys of _refs are valid UUIDs
  * that referenced objects are themselves valid MRDI

The function produces an error if validation fails and returns null (Macaulay2Doc),
on success.

+--------------------------------------------------------------------------+
|i1 : s = saveMRDI 5                                                       |
|                                                                          |
|o1 = {"_ns": {"Macaulay2": ["https://macaulay2.com", "1.26.05"]}, "_type":|
|     "ZZ", "data": "5"}                                                   |
+--------------------------------------------------------------------------+
|i2 : validateMRDI s                                                       |
+--------------------------------------------------------------------------+

Ways to use validateMRDI:
=========================

  * "validateMRDI(HashTable)"
  * "validateMRDI(String)"
  * "validateMRDI(Thing)"

For the programmer
==================

The object validateMRDI, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MRDI.m2:860:0.