Semantic Mapping (.NET)

SDL Digital Experience Accelerator provides default semantic mapping, but you can mapping fields explicitly, exclude properties from mapping, and map Schemas.

Default semantic mapping

If you do not annotate your View Models with semantics, the following default semantics are applied:
  • When attempting to populate a View Model property from the Content Manager model, look for a Schema field with the same name, but using camelCasing instead of PascalCasing. For example, the property Headline is mapped to Schema field headline.
  • When attempting to populate a property of type List<T>, remove any trailing s's from the property name. For example, the Paragraphs property is mapped to Schema field paragraph.

Mapping fields explicitly

If the default semantics are not sufficient, for example if the Schema field names do not make sensible View Model property names, you can specify the SemanticProperty attribute to map fields explicitly:

[SemanticProperty("internalLink")]
public string Link { get; set; }

Mapping multiple Schema fields to a single View Model property

If your link property contains an external or an internal link, modeled in the Content Manager using optional fields, internalLink (a Component Link) and externalLink (an External Link), you can specify semantic property attributes for both and the implementation will populate the model with whichever links it finds. You therefore do not have to put this logic in the Model or View.

[SemanticProperty("internalLink")]
[SemanticProperty("externalLink")]
public string Link { get; set; }

Mapping multiple Schemas to a single Entity

You can add SemanticEntity attributes to the View Model class to map multiple Schemas to a single Entity.

For example, a Teaser View Model is a generic block of content containing headline, summary text and link that you can use to create content teasers that link through to other content on the Web site. You have a corresponding Teaser Schema in the Content Manager, but you also want to use the Teaser views for other types of content that has similar fields, for example an article, or an event. Add SemanticEntity attributes to map the different field names in the different Schemas to a single Entity, or to control which fields map to which properties for each Schema:

using System;
using Sdl.Web.Common.Models;

namespace Example.Models
{
  [SemanticEntity(EntityName = "Article", Prefix = "a", Vocab = CoreVocabulary)]
  [SemanticEntity(EntityName = "Event", Prefix = "e", Vocab = "http://example.com/web/Schemas")]
  public class Teaser : EntityModel
  {
    [SemanticProperty("e:eventName")]
    public string Headline { get; set; }
    [SemanticProperty("e:description")]
    [SemanticProperty("a:introText")]
    public string Summary { get; set; }
    [SemanticProperty("a:_self")]
    [SemanticProperty("e:_self")]
    public string Link { get; set; }
  }
}
where
  • SemanticEntity EntityName must correspond to the XML Root Element name on the Schema.
  • Vocab must match the Schema namespace.
  • use the CoreVocabulary default vocabulary To map from Schemas in the DXA Core
  • _self is a special syntax for links:
    • For a String or Link type property, it will resolve a dynamic link to the source Component and put the result in the property value.
    • For a MediaItem type property, it will attempt map the whole source component to the property value, useful when creating summary or teaser Views/View Models which link through to the same content but show a different (complete) View/View Model.

Excluding properties from mapping

If you have View Model properties that you want to exclude from mapping, for example if part of your View Model is populated by search or an other external data source, you can specify exclusions for each single property:

[SemanticProperty(IgnoreMapping = true)]
public int ResultCount { get; set; }

You can also turn off default mapping of properties at View Model level, in which case default semantics are not be applied and only properties with explicit property semantics will be mapped. The the following example, only the Headline will be mapped:

using System;
using Sdl.Web.Common.Models;

namespace Example.Models
{
  [SemanticDefaults(MapAllProperties = false)]
  public class SearchResults : EntityModel
  {
    [SemanticProperty("headline")]
    public string Headline { get; set; }
    public int ResultCount { get; set; }
    public List<Teaser> Results { get; set;}
  }
}