# sz-sdk-json-type-definition

If you are beginning your journey with [Senzing],
please start with [Senzing Quick Start guides].

You are in the [Senzing Garage] where projects are "tinkered" on.
Although this GitHub repository may help you understand an approach to using Senzing,
it's not considered to be "production ready" and is not considered to be part of the Senzing product.
Heck, it may not even be appropriate for your application of Senzing!

## :warning: WARNING: sz-sdk-json-type-definition is still in development :warning: _

At the moment, this is "work-in-progress" with Semantic Versions of `0.n.x`.
Although it can be reviewed and commented on,
the recommendation is not to use it yet.

## Synopsis

The Senzing `sz-sdk-json-type-definition` uses [JSON Type Definition]
to model the JSON that is returned from Senzing SDK calls.

Code generated from this model improves compile-time type checking
and code-completion in Integrated Development Environments (IDE)
(e.g. "VSCode's IntelliSense").

## Overview

By using the code generated by [JSON Type Definition],
JSON returned by the Senzing SDK calls are easier to parse.
Examples:

1. Python - [main.py]
1. Go - [main.go]
1. Java - [Main.java]
1. Typescript - [main.ts]
1. C-sharp [Program.cs]

The actual specification is [senzingsdk-RFC8927.json].

From this specification, code is generated for the following languages:

1. [csharp]
1. [go]
1. [java]
1. [python]
1. [ruby]
1. [rust]
1. [typescript]

## Use

1. Python comparison:
    1. Here's how to parse a Senzing JSON response **without** `senzing-json`:

        ```python
        result = sz_engine.get_virtual_entity_by_record_id(record_keys, flags)
        feature_list = result.get("RESOLVED_ENTITY", {}).get("FEATURES", {}).get("NAME", [])
        ```

        1. Note that the JSON keys and datatypes of the values must be known ahead of time.
           Also, this method is subject to typographical errors.

    1. Here's how to parse a Senzing JSON response **with** `senzing-json`:

        ```python
        result = sz_engine.get_virtual_entity_by_record_id(record_keys, flags)
        virtual_entity = SzEngineGetVirtualEntityByRecordIDResponse.from_json_data(result)
        feature_list = virtual_entity.resolved_entity.features["NAME"]
        ```

        1. When using an IDE, the fields and datatypes are supplied by the IDE's code-completion.
        Typos will be flagged by the IDE.

## References

1. [Development]
1. [Errors]
1. [Examples]
1. Packages
    1. [Go package reference]

[csharp]: csharp
[Development]: docs/development.md
[Errors]: docs/errors.md
[Examples]: docs/examples.md
[go]: go/typedef
[java]: java
[JSON Type Definition]: https://jsontypedef.com/
[main.go]: main.go
[Main.java]: Main.java
[main.py]: main.py
[main.ts]: main.ts
[Go package reference]: https://pkg.go.dev/github.com/senzing-garage/sz-sdk-json-type-definition
[Program.cs]: csharp/Program.cs
[python]: python/senzing_typedef
[ruby]: ruby
[rust]: rust
[Senzing Garage]: https://github.com/senzing-garage
[Senzing Quick Start guides]: https://docs.senzing.com/quickstart/
[Senzing]: https://senzing.com/
[senzingsdk-RFC8927.json]: senzingsdk-RFC8927.json
[typescript]: typescript
