JsonApiSerializer 2.0.1
dotnet add package JsonApiSerializer --version 2.0.1
NuGet\Install-Package JsonApiSerializer -Version 2.0.1
<PackageReference Include="JsonApiSerializer" Version="2.0.1" />
paket add JsonApiSerializer --version 2.0.1
#r "nuget: JsonApiSerializer, 2.0.1"
// Install JsonApiSerializer as a Cake Addin #addin nuget:?package=JsonApiSerializer&version=2.0.1 // Install JsonApiSerializer as a Cake Tool #tool nuget:?package=JsonApiSerializer&version=2.0.1
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());
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["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[] article = JsonConvert.DeserializeObject<Article>(json, new JsonApiSerializerSettings());
Assert.Equal("http://example.com/articles/1/relationships/author", article.Author.links["self"].Href);
Assert.Equal("http://example.com/articles/1/author", article.Author.links["related"].Href);
Resource Identifiers
json:api specification allows defining metadata at the resource identifier level. By default this resource identifier meta
is folded into the object's meta
(if the field is present).
However if you have distinct resource identifier meta
and resource object meta
you may define a relationship of type IResourceIdentifier<T>
. This object will populate the meta
property and place the resource object details within Value
field.
{
"data": {
"type": "articles",
"id": "1",
"attributes": {
"title": "JSON API paints my bikeshed!"
},
"relationships": {
"author": {
"meta": {
"verified": true,
},
"data": { "type": "people", "id": "9" }
}
}
},
"included": [{
"type": "people",
"id": "9",
"attributes": {
"first-name": "Dan",
"last-name": "Gebhardt",
"twitter": "dgeb"
},
"meta": {
"verified" : false
}
}]
}
public class Article
{
public string Id { get; set; }
public string Title { get; set; }
public ResourceIdentifier<Person> Author { get; set; }
}
Article[] article = JsonConvert.DeserializeObject<Article[]>(json, new JsonApiSerializerSettings());
Assert.Equal(true, article.Author.meta["verified"]); //resource identifier meta
Assert.Equal(true, article.Author.Value.meta["verified"]); //object meta
Links
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);
Determine object type during deserialization
The default behaviour is to assume that the object type declared on your property is the type that will be created during deserialization. However there are times where you may want the property to be declared as an interface or abstract class and then determine the actual type to instantiate during deserialization.
This can be achieved by creating a custom JsonConvertor
extending from ResoruceObjectConvertor
and overriding CreateObject
. You can then provide custom logic in creating the object, typically this would be done by examing hte json:api type.
public class MyTypeDeterminingResourceObjectConvertor : ResourceObjectConverter
{
protected override object CreateObject(Type objectType, string jsonapiType, JsonSerializer serializer)
{
switch (jsonapiType)
{
case "vip-person":
return new PersonVIP();
case "person":
return new Person();
default:
return base.CreateObject(objectType, jsonapiType, serializer);
}
}
}
This convertor can be added into the system in a number of ways
- Adding it globally to all resource objects by specifiying during the creation of the
JsonApiSerializerSettings
var settings = new JsonApiSerializerSettings(new MyTypeDeterminingResourceObjectConvertor())
Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, settings);
- Adding to everything that matches the
CanConvert
method on your customer converter. If doing this you would want to override theCanConvert
method so it only targets object types you want to use the new convertor.
var settings = new JsonApiSerializerSettings()
settings.Converters.Add(new MyTypeDeterminingResourceObjectConvertor())
Article[] articles = JsonConvert.DeserializeObject<Article[]>(json, settings);
- Add to your model by annotating it with a
JsonConvertorAttribute
. This behaviour is identical to usage by json.net
[JsonConvertor(typeof(MyTypeDeterminingResourceObjectConvertor))]
public IPerson Author {get; set;}
Integrating with Microsoft.AspNetCore.Mvc
You can configure json:api to be the default serialization for your MVC site by reconfiguring the JsonInputFormatter
and JsonOutputFormatter
to use the JsonApiSerializerSettings
public class Startup
{
// ...
public void ConfigureServices(IServiceCollection services)
{
// ...
var sp = services.BuildServiceProvider();
var logger = sp.GetService<ILoggerFactory>();
var objectPoolProvider = sp.GetService<ObjectPoolProvider>();
services.AddMvc(opt => {
var serializerSettings = new JsonApiSerializerSettings();
var jsonApiFormatter = new JsonOutputFormatter(serializerSettings, ArrayPool<Char>.Shared);
opt.OutputFormatters.RemoveType<JsonOutputFormatter>();
opt.OutputFormatters.Insert(0, jsonApiFormatter);
var jsonApiInputFormatter = new JsonInputFormatter(logger.CreateLogger<JsonInputFormatter>(), serializerSettings, ArrayPool<Char>.Shared, objectPoolProvider);
opt.InputFormatters.RemoveType<JsonInputFormatter>();
opt.InputFormatters.Insert(0, jsonApiInputFormatter);
});
}
}
Product | Versions 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 | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | 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 | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- Newtonsoft.Json (>= 13.0.3)
NuGet packages (12)
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 | 24,843 | 4/20/2024 |
1.7.4 | 1,588,942 | 12/16/2019 |
1.7.3 | 101,716 | 7/17/2019 |
1.7.2 | 1,485 | 7/13/2019 |
1.7.1 | 940 | 7/13/2019 |
1.7.0 | 54,900 | 3/24/2019 |
1.6.2 | 18,272 | 1/9/2019 |
1.6.1 | 19,240 | 12/10/2018 |
1.6.0 | 7,317 | 11/26/2018 |
1.6.0-beta01 | 858 | 11/19/2018 |
1.5.1 | 25,626 | 10/31/2018 |
1.5.0 | 1,086 | 10/30/2018 |
1.4.0 | 242,793 | 7/15/2018 |
1.3.2 | 1,414 | 7/12/2018 |
1.3.1 | 52,798 | 4/26/2018 |
1.3.0 | 4,632 | 4/10/2018 |
1.2.3 | 1,574 | 4/2/2018 |
1.2.2 | 4,669 | 3/20/2018 |
1.2.1 | 13,189 | 3/18/2018 |
1.2.0 | 9,281 | 2/8/2018 |
1.1.0 | 15,508 | 1/4/2018 |
1.0.0 | 8,555 | 11/4/2017 |
0.10.0 | 1,342 | 11/4/2017 |
0.9.18 | 13,500 | 9/2/2017 |
0.9.16 | 2,236 | 8/2/2017 |
0.9.15 | 1,400 | 8/1/2017 |
0.9.14 | 1,580 | 7/21/2017 |
0.9.13 | 5,621 | 7/12/2017 |
0.9.11 | 1,577 | 6/6/2017 |
0.9.10 | 1,342 | 6/6/2017 |
0.9.9 | 1,362 | 5/25/2017 |
0.9.8 | 1,379 | 5/23/2017 |
0.9.7 | 1,388 | 5/17/2017 |
0.9.6 | 1,369 | 5/17/2017 |
0.9.4 | 1,730 | 4/19/2017 |
0.9.3 | 1,412 | 4/11/2017 |
0.9.2 | 1,378 | 4/10/2017 |
0.9.1 | 1,277 | 4/4/2017 |
0.9.0 | 1,461 | 4/2/2017 |