JsonApiSerializer 0.10.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package JsonApiSerializer --version 0.10.0                
NuGet\Install-Package JsonApiSerializer -Version 0.10.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="JsonApiSerializer" Version="0.10.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add JsonApiSerializer --version 0.10.0                
#r "nuget: JsonApiSerializer, 0.10.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install JsonApiSerializer as a Cake Addin
#addin nuget:?package=JsonApiSerializer&version=0.10.0

// Install JsonApiSerializer as a Cake Tool
#tool nuget:?package=JsonApiSerializer&version=0.10.0                

JsonApiSerializer

The JsonApiSerializer provides configurationless serializing and deserializing objects into the json:api format.

It is implemented as an JsonSerializerSettings for Json.Net with usage being the standard Json.Net methods passing in a JsonApiSerializerSettings

//To serialize a POCO in json:api format
string json = JsonConvert.SerializeObject(articles, new JsonApiSerializerSettings());

//To deserialize to a POCO from json:api format
Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, new JsonApiSerializerSettings());

NuGet version

Example

Given an object model like:

public class Article
{
    public string Id { get; set; }

    public string Title { get; set; }

    public Person Author { get; set; }

    public List<Comment> Comments { get; set; }
}

public class Comment
{
    public string Id { get; set; }

    public string Body { get; set; }

    public Person Author { get; set; }
}

public class Person
{
    public string Id { get; set; }

    [JsonProperty(propertyName: "first-name")] //uses standard Json.NET attributes to control serialization
    public string FirstName { get; set; }

    [JsonProperty(propertyName: "last-name")]
    public string LastName { get; set; }

    public string Twitter { get; set; }
}

Deserialization

and json:api content that look something like

{
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
        "title": "JSON API paints my bikeshed!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      },
      "comments": {
        "data": [
          { "type": "comments", "id": "5" },
          { "type": "comments", "id": "12" }
        ]
      }
    }
  }],
  "included": [{
    "type": "people",
    "id": "9",
    "attributes": {
      "first-name": "Dan",
      "last-name": "Gebhardt",
      "twitter": "dgeb"
    },
  }, {
    "type": "comments",
    "id": "5",
    "attributes": {
      "body": "First!"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "2" }
      }
    },
  }, {
    "type": "comments",
    "id": "12",
    "attributes": {
      "body": "I like XML better"
    },
    "relationships": {
      "author": {
        "data": { "type": "people", "id": "9" }
      }
    },
  }]
}

We can deserialize with

Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, new JsonApiSerializerSettings());

Serialization

We can also generate the JSON from our object model


var author = new Person
{
    Id = "9",
    FirstName = "Dan",
    LastName = "Gebhardt",
    Twitter = "dgeb",
};

var articles = new[] {
    new Article
    {
        Id = "1",
        Title = "JSON API paints my bikeshed!",
        Author = author,
        Comments = new List<Comment>
        {
            new Comment
            {
                Id = "5",
                Body = "First!",
                Author = new Person
                {
                    Id = "2"
                },
            },
            new Comment
            {
                Id = "12",
                Body = "I like XML better",
                Author = author,
            }
        }
    }
};

//will produce the same json:api json value
string json = JsonConvert.SerializeObject(articles, new JsonApiSerializerSettings());

Extracting more properties

json:api allows for additional information to be stored at objects and relationships, We provide some helper classes that allows you to access these properties.

DocumentRoot

DocumentRoot<TData> allows you to get and set json:api values at the root document level

{
	"jsonapi": {
		"version":"1.0"
	},
	"links": {
		"self": "http://example.com/articles",
	},
	"meta": {
		"created": "2017-04-02T23:28:35"
	},
	"data": [{
  		"id" : "1",
		"type": "articles",
		"attributes": {
	  		"title": "document root example"
		}
	}]
}
DocumentRoot<Article[]> articlesRoot = JsonConvert.DeserializeObject<DocumentRoot<Article[]>>(json, new JsonApiSerializerSettings());
Assert.Equal("1.0" articlesRoot.JsonApi.Version);
Assert.Equal("http://example.com/articles", articlesRoot.Links["self"].Href);
Assert.Equal("2017-04-02T23:28:35", articlesRoot.Meta["self"]["created"]);

Relationships

Relationship<TData> can be used in an object to get and set additional json:api around relationships such as links or meta

{
	"data": [{
		"type": "articles",
		"id": "1",
		"attributes": {
			"title": "JSON API paints my bikeshed!"
		},
		"relationships": {
			"author": {
				"links": {
				  "self": "http://example.com/articles/1/relationships/author",
				  "related": "http://example.com/articles/1/author"
				},
				"data": { "type": "people", "id": "9" }
			}
		}
	}]
}
public class Article
{
    public string Id { get; set; }

    public string Title { get; set; }

    public Relationship<Person> Author { get; set; }
}
Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, new JsonApiSerializerSettings());
Assert.Equal("http://example.com/articles/1/relationships/author", articles[0].links["self"].Href);
Assert.Equal("http://example.com/articles/1/author", articles[0].links["related"].Href);

Link can be used to store link values. json:api supports links as either a string or as an object. JsonApiSerializer normalizes this behaviour so in the object model they are always an object.

A Links class is also provided to store a dictionary of links that is typically stored on json:api objects

Types

If you dont specify a type property on your object model JsonApiSerializer will use the class name. If you want to modify this behaviour it is as simple as putting a Type property on a class

public class Person
{
	public string Type { get; set; } = "people"; //sets type to "people"

	public string Id { get; set; }

	[JsonProperty(propertyName: "first-name")]
	public string FirstName { get; set; }

	[JsonProperty(propertyName: "last-name")]
	public string LastName { get; set; }

	public string Twitter { get; set; }
}

Determining relationship objects

By default any class with an "Id" is considered a Resource Object, and it will be treated as a relationship during serialization and deserialization.

This can be overrided during initialization by providing your own JsonConverter (it is strongly recommneded you extend ResourceObjectConverter) when you create the JsonApiSerializerSettings. Your custom 'JsonConverter can override the `CanConvert(Type type)' method.

var settings = new JsonApiSerializerSettings(new MyOwnJsonSerializer())
Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, settings);
Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.0 is compatible.  netstandard1.1 was computed.  netstandard1.2 was computed.  netstandard1.3 was computed.  netstandard1.4 was computed.  netstandard1.5 is compatible.  netstandard1.6 was computed.  netstandard2.0 was computed.  netstandard2.1 was computed. 
.NET Framework net45 is compatible.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 was computed. 
Windows Phone wp8 was computed.  wp81 was computed.  wpa81 was computed. 
Windows Store netcore was computed.  netcore45 was computed.  netcore451 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (13)

Showing the top 5 NuGet packages that depend on JsonApiSerializer:

Package Downloads
Pubg-DotNet

Sync and Async client library for communicating with the Pubg Developer API supporting .net standard 2.0

Clinical6SDK

An easy to use .NET SDK for Clinical6 SDK (a product of Parallel6)

Xamarin.Forms.Clinical6

A library for Clinical6 UI components (a product of Parallel6)

Rethought.Battlerite.NET.Rest

This package is responsible to interact with the Battlerite REST API. Part of the Battlerite.NET library.

Xamarin.Forms.Clinical6.iOS

A library for Clinical6 UI Controls Renders (a product of Parallel6)

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.1 44,506 4/20/2024
1.7.4 1,656,640 12/16/2019
1.7.3 108,739 7/17/2019
1.7.2 1,492 7/13/2019
1.7.1 945 7/13/2019
1.7.0 55,329 3/24/2019
1.6.2 21,896 1/9/2019
1.6.1 19,282 12/10/2018
1.6.0 7,322 11/26/2018
1.6.0-beta01 864 11/19/2018
1.5.1 26,178 10/31/2018
1.5.0 1,092 10/30/2018
1.4.0 257,008 7/15/2018
1.3.2 1,431 7/12/2018
1.3.1 53,334 4/26/2018
1.3.0 4,654 4/10/2018
1.2.3 1,582 4/2/2018
1.2.2 4,697 3/20/2018
1.2.1 13,206 3/18/2018
1.2.0 9,310 2/8/2018
1.1.0 15,558 1/4/2018
1.0.0 8,754 11/4/2017
0.10.0 1,356 11/4/2017
0.9.18 13,998 9/2/2017
0.9.16 2,243 8/2/2017
0.9.15 1,408 8/1/2017
0.9.14 1,586 7/21/2017
0.9.13 5,645 7/12/2017
0.9.11 1,583 6/6/2017
0.9.10 1,349 6/6/2017
0.9.9 1,376 5/25/2017
0.9.8 1,385 5/23/2017
0.9.7 1,397 5/17/2017
0.9.6 1,378 5/17/2017
0.9.4 1,738 4/19/2017
0.9.3 1,419 4/11/2017
0.9.2 1,385 4/10/2017
0.9.1 1,291 4/4/2017
0.9.0 1,476 4/2/2017