Avoiding SharePoint Internal Name Pain

For the majority of users, the inner workings of SharePoint don’t hold much interest, but there is one aspect that you might find worthwhile to understand, especially if you are responsible for creating lists or libraries that yourself or others may want to customise later with XSLT, DisplayTemplates or even access using the Client Side Object Model (CSOM).

You’ll notice that I mentioned XSLT and Display Templates in the same sentence there, not just because XSLT hasn’t gone away completely in SharePoint 2013, but also because what I’m writing about here applies equally in SharePoint 2007, 2010, 2013 and Office 365.

Developers have been aware of SharePoint internal name pain for sometime. Ever since the first time I ever wrote a CAML query, I swiftly became aware of the difference between the display name used in the SharePoint UI and the name that SharePoint used under the hood. For the average end user however, they frankly don’t care because they never see the issue.

What is SharePoint Internal Name Pain?

Let me give you a (completely made-up) example:-

Jane is an Export Executive for the Ivory Coast Trading company, a company responsible for the export of various crops and spices from the ivory Coast. She needs to keep track of both the number of Coffee Beans shelled each month and the number of coffee beans subsequently sold.

She creates her list and starts to add some columns. The first column she adds is a simple number field, which she names "The Number of Ivory Coast Coffee Beans shelled".

SharePoint Internal Name Pain_image001

Ok, a slightly exaggerated example, but there’s good reason as I want to show you what happens not just to names with spaces, but also those names over a certain length.

After our column is created if we click on the column name in our list settings to enter the edit column screen and cast our eyes to the address bar in our browser, we can see what SharePoint has called our column internally.

SharePoint Internal Name Pain_image002

This dear reader is an example of SharePoint Internal Name Pain! And just to confuse matters, the browser has encoded our actual name a second time! Let’s dissect this a little.

The browser is displaying the following in the Address Bar:-


This is actually the internal name, encoded for use in a URL, the actual internal name replaces the %5F with the underscore "_" character:-


But that’s not much better! SharePoint has replaced the single space character with 7 new Characters (This is called Unicode encoding) which not only means we’ve added a LOT of characters to our internal name, we’ve also hit the SharePoint limit of 32 characters. As a result when you view the internal name it really doesn’t mean anything and certainly doesn’t tell you what data is being held in the list column.

And as if that on it’s own wasn’t painful enough, Jane has just added a second column to represent the "The number of Ivory Coast Coffee Beans sold"

If we do the same trick as before, decode the value in our URL by replacing the %5F with the _, you’ll find we’re left with:-


As we hit the character limit, SharePoint realised that we already had a column with that name, so it helpfully stuck a 0 on the end! So we now have 2 almost identical internal names and no easy way to ensure which ones which without going into the list settings each time and testing.

The Solution?

Well the solution is quite simple; just make sure that you are sensible when creating your list columns in the first place! Avoiding the use of non-alphanumeric characters in your names will make them much simpler to read.

In our example above, Jane could have created the columns using the names ICBeansShelled and ICBeansSold. Once the columns have been created, you can then change the Display Name to be anything and the nice neat internal name remains the same.

SharePoint Internal Name Pain_image003

SharePoint Internal Name Pain_image004

I’m just an end user, why would I care?

Firstly your IT Pros will thank you, especially if you ever ask them to go an do anything on the server through powershell that requires them to do anything to your lists.

Secondly, your Developers will certainly thank you… writing CAML queries at the best of times is hard enough. Adding long meaningless field names to that just makes their job ten times harder and delays the delivery of whatever you’ve asked them to do.

And finally, if you’re a power-user (or aspiring to be one) then you will thank yourself as soon as you open SharePoint Designer and play with a list view, or start to write a display template in JavaScript and need to access your data through the context object.



I think at this point, you’ll agree which is the easiest to read and understand. Especially when you go back 6 months later to make a change! You’ll be glad at that point that you learned to avoid SharePoint Internal Name Pain!



    • Perry on Thu 29 Oct 15 at 6:18 pm
    • Reply

    It is important to note that there are three names for every field. There is the DisplayName (what the user types), the StaticName (what it converts to with the ugly mappings for spaces and punctuation), and the InternalName (which is modified from the StaticName as necessary to make it unique to the current list).

    The SharePoint APIs use various of these three forms in various places, and often are poorly documented.

    1. Thanks for the note Perry,

      Invariably the Static Name is identical to the Internal Name, there’s only a few cases where they may be different. With respect to things like JavaScript display templates and Search metadata mapping, the Internal name is ALWAYS used, with the Display name and the Static name only used for display purposes.

      Likewise with the work I’ve done on CSOM, I’ve only seen the Internal Name used but as I don’t use REST heavily I can’t really comment on whether the Static Name is ever used in preference to the Internal Name..

Leave a Reply

Your email address will not be published.


This site uses Akismet to reduce spam. Learn how your comment data is processed.