Graph file format
Each class is a *.netpc.json file. It is a plain, deterministic JSON document designed to be
readable and mergeable in an ordinary git workflow: opened in a diff viewer, reviewed in a pull
request, or resolved by hand when two branches touch the same file.
Schema and editor support
Every graph starts with a $schema pointer:
{
"$schema": "https://danielmeza.github.io/netprints/schemas/netpc.v1.schema.json",
"schemaVersion": 1,
...
}
$schema is informational only — NetPrints never fetches it, and ignores it on read. Editors that
understand JSON Schema (VS Code, Rider) use it for validation and completion once the URL resolves
(it is published from the NetPrints Sdk repository's
own site, see schemas/netpc.v1.schema.json in the repository
for the schema itself).
Version control
A .netpc.json file is written in a canonical form: 2-space indentation, sorted maps, and a fixed
property order, so the same graph always serializes to the same bytes. Short, self-contained values
(a node's connections, a layout position, a typed constant) are written on a single line each rather
than spread across several; everything else is one property per line. A file is only rewritten when
its class actually changed, so an unrelated build or open never touches files you didn't edit.
A graph's connections are always written sorted by from, then to (ordinal string order), by both the
editor and netprints format; the loader accepts any order, and format --check reports a file whose
connections are in another order.
Every project gets a .gitattributes file next to it (written once, when the project is created)
with:
*.netpc.json text eol=lf
*.netpc.g.cs text eol=lf
This keeps line endings consistent across Windows, Linux and macOS checkouts, which matters for a line-oriented diff to stay meaningful.
What a change looks like in a diff
Moving a node changes exactly one line, the node's entry in layout:
- "n00000000057k3": [420, 112]
+ "n00000000057k3": [460, 140]
Adding a node adds one node block (or, for a simple node, one line), one line per new connection, and one new layout line — nothing else in the file shifts. Node ids are randomly generated rather than sequential counters, so two branches that each add a node do not collide; connections and layout entries reference nodes and members by id, not by position in an array, so reordering a method or inserting a parameter into a called method's signature does not silently retarget an unrelated connection or move someone else's layout entry.
That combination is what keeps a merge to "both sides added a block; git keeps both" instead of a conflict spanning the whole nodes array — see the graph file format contract for the full schema, identifier rules and canonical-writing rules behind this.
Custom event arguments
A custom event entry ("$kind": "eventEntry") can declare arguments. They are written as an optional
arguments array, after argumentCount:
{ "$kind": "eventEntry", "argumentCount": 2,
"pins": [ { "pin": "out.data.Input0", "name": "amount" }, { "pin": "out.data.Input1", "name": "source" } ],
"arguments": [ { "type": { "name": "System.Int32" } }, { "type": { "name": "System.String" } } ] }
The argument names are the names of the argument pins in pins; arguments holds only the types. A file
that also has a name in each argument is still read; a name that is not a valid, unique C# identifier is
replaced by the pin's name (or InputN) with the warning NPD011.
The property is optional in version 1 and is written only when an argument has a declared type other
than object; an entry without it is written exactly as before, so existing files do not change.
argumentCount is still written, which is what a reader that does not know arguments uses: it
creates that many arguments typed object. This means an older editor drops custom event arguments
when it saves the graph: it reads the entry with untyped arguments and writes it back without the
arguments array. An override entry never writes arguments; its arguments come from the base method.
Calls with out and ref parameters
A call node gets one output data pin for each out or ref parameter of its method, after the pins for the
return values. The pin is keyed by the parameter name (out.data.<parameterName>; a parameter named Exception is keyed
out.data.param:Exception, because out.data.Exception belongs to the exception pin) and carries the parameter's
value after the call. The pins are derived from the method when the graph loads, so the file format is unchanged
and version 1 stays additive: a graph that wires nothing to the new pins is written exactly as before, and a
connection to one is an ordinary connection entry. A void method with an out parameter can be pure; an out
or ref input still needs a variable connected to it.
Unknown members
A member this build does not know, at any level of a graph file (the class, a graph, a method, a node, a
pin, a connection), survives a load and save of the document. It is kept as an opaque value, written after
the known members of its object and in ordinal key order. netprints format keeps it, netprints show
prints it as unknown <key> <value>, and the merge driver takes the change of whichever side changed it,
or reports a conflict when both sides changed the same member to different values. This lets a newer
editor, or an extension, add a field without an older editor discarding it. Inside a type, method, variable or
value reference, format, show and the merge driver keep an unknown member, but the editor rewrites those
references from its own types, so its save drops it.
Node data versions
A node of an extension kind may carry a kindVersion member: the version of the data its kind wrote it with. The member
is written only when the kind declares a data version above 0, so every built-in node, and every file written before an
extension versions its data, stays byte for byte as it was. A node without the member has version 0.
When the extension declares a newer data version, the editor upgrades the node as the file opens: the migrations the
extension registered for that kind run in order, from the node's stored version up to the current one, and the node is
saved with the new kindVersion. A migration changes only the JSON of its own node. An older editor that does not know
the kind keeps the node, kindVersion included, as an unknown node.
Version control
Graph files are designed to work well in git: they are text, canonical (deterministic bytes), and
merge-friendly. See Git workflow for the show command (readable diffs), the merge driver
(smart merging), and checks for canonical form and current generated code. Both .netpc.json and
netprints.catalog.json files have schemas prepared for SchemaStore registration (see the Git
workflow section for details).
Generated code
Each graph file has a matching <Name>.netpc.g.cs, generated at build time and committed alongside
it. It is not marked as generated for diff purposes, so it shows up in pull request reviews too —
see Projects for how that pairing works and why the generated file should never be
hand-edited.