adding micro markup to the site

My name is Nikita Neminushchiy, I am a leading software engineer for the financial marketplace “Vyberu.ru”. In this article I would like to tell you how micro markup was implemented on our website and share my experience in its refinement.

A few words about what micro markup is

Website micromarking is an additional (optional) HTML code markup that helps search engines such as Google, Yandex, better understand the structure and content of web pages. It adds metadata to content so search engines can more accurately interpret what's on the page. The micro-markup itself is not visible to the user, but it significantly influences how the site is displayed in search results, since search engines include data from the micro-markup in their search results.

In other words, a site with micro markup will take up more space on the search engine results page than a site without it and will displace competitors. Also, by serving up key parts of the page's content, such a site has a better chance of capturing the user's attention and motivating him to click on the link and open the site.

There are two most popular microdata dictionaries and several of their syntaxes:

Schema.org is a standard developed by Google, Bing, Yahoo and Yandex. That is, this is the micro-markup that is used by search engines;
Open Graph is microdata developed by Facebook. It is used to display information on social networks: it determines how the post will look: what image, title and description will be shown if you share a link with someone.

Today we will talk about Schema.org.

Old problem solution

Our portal primarily uses microdata from the Schema.org dictionary in two syntax options: less “microdata” and more “JSON-LD”.

The first option is less convenient, since the micro-markup data is smeared across the HTML markup of the page, which clogs it and makes it difficult for developers to support such code.

The second option is json, which is inserted into the

All he needs to do is write the following code:

WebSite website = new()
{
    AlternateName = "An Alternative Name",
    Name = "Your Site Name",
    Url = new Uri("https://example.com")
};
string jsonLd = website.ToString();

Due to the fact that each field has its own type, it is more difficult for the developer to make the mistake of “hitting himself in the eye with a spoon.” But you can still make a mistake, since some properties are multi-type, that is, they can contain more than one variant of the data type. And since C# is a strongly typed language, the implementation of this feature has certain limitations. To get around these, Schema.NET implements helper types such as the Values structure.

For example, this is what the Brand property looks like in the Product type:

[JsonPropertyName("brand")]
[JsonPropertyOrder(110)]
[JsonConverter(typeof(ValuesJsonConverter))]
public Values<IBrand, IOrganization> Brand { get; set; }

From the code you can see that the property can accept all models that implement either the IBrand interface or the IOrganization interface. This fact, of course, is documentation in itself, but in order to make filling out models convenient and the code visual: the Values structure implements many options for implicit type casts.

One such implicit type cast looks like this:

public static implicit operator Values<T1, T2>(object[] array) => new(array);

This allows you to insert an arbitrary array into it and not immediately notice that the “sandwich” is “without butter.” At the execution stage there will be no error, just in the final json the property will be empty.

Another shortcoming of Schema.NET is the fact that all the data types it contains are located in the same namespace. Because of this, for example, in Schema.NET there is no PaymentCard type as a financial product, but there is PaymentCard as a payment method. And if you look at the description of this type https://schema.org/PaymentCard in the dictionary, you can see that there are two of them with the same name, but from different heirs.

Fortunately, in Schema.NET, all data types are not closed from inheritance, and following the example, you can create the type you need. But for the rest, beautiful marquise, everything is fine, everything is fine...